iatoolkit 0.11.0__py3-none-any.whl → 0.66.2__py3-none-any.whl

iatoolkit/services/query_service.py

@@ -4,11 +4,11 @@
 # IAToolkit is open source software.
 
 from iatoolkit.infra.llm_client import llmClient
+from iatoolkit.services.profile_service import ProfileService
 from iatoolkit.repositories.document_repo import DocumentRepo
 from iatoolkit.repositories.profile_repo import ProfileRepo
 from iatoolkit.services.document_service import DocumentService
 from iatoolkit.repositories.llm_query_repo import LLMQueryRepo
-
 from iatoolkit.repositories.models import Task
 from iatoolkit.services.dispatcher_service import Dispatcher
 from iatoolkit.services.prompt_manager_service import PromptService
@@ -21,6 +21,7 @@ import logging
 from typing import Optional
 import json
 import time
+import hashlib
 import os
 
 
@@ -30,6 +31,7 @@ class QueryService:
     @inject
     def __init__(self,
                  llm_client: llmClient,
+                 profile_service: ProfileService,
                  document_service: DocumentService,
                  document_repo: DocumentRepo,
                  llmquery_repo: LLMQueryRepo,
@@ -39,6 +41,7 @@ class QueryService:
                  dispatcher: Dispatcher,
                  session_context: UserSessionContextService
                  ):
+        self.profile_service = profile_service
         self.document_service = document_service
         self.document_repo = document_repo
         self.llmquery_repo = llmquery_repo
@@ -55,107 +58,126 @@ class QueryService:
             raise IAToolkitException(IAToolkitException.ErrorType.API_KEY,
                                "La variable de entorno 'LLM_MODEL' no está configurada.")
 
+    def _build_context_and_profile(self, company_short_name: str, user_identifier: str) -> tuple:
+        # this method read the user/company context from the database and renders the system prompt
+        company = self.profile_repo.get_company_by_short_name(company_short_name)
+        if not company:
+            return None, None
 
-    def llm_init_context(self,
-                         company_short_name: str,
-                         external_user_id: str = None,
-                         local_user_id: int = 0,
-                         model: str = ''):
-        start_time = time.time()
-        if not model:
-            model = self.model
+        # Get the user profile from the single source of truth.
+        user_profile = self.profile_service.get_profile_by_identifier(company_short_name, user_identifier)
 
-        # Validate the user and company
-        user_identifier, is_local_user = self.util.resolve_user_identifier(external_user_id, local_user_id)
+        # render the iatoolkit main system prompt with the company/user information
+        system_prompt_template = self.prompt_service.get_system_prompt()
+        rendered_system_prompt = self.util.render_prompt_from_string(
+            template_string=system_prompt_template,
+            question=None,
+            client_data=user_profile,
+            company=company,
+            service_list=self.dispatcher.get_company_services(company)
+        )
+
+        # get the company context: schemas, database models, .md files
+        company_specific_context = self.dispatcher.get_company_context(company_name=company_short_name)
+
+        # merge context: company + user
+        final_system_context = f"{company_specific_context}\n{rendered_system_prompt}"
+
+        return final_system_context, user_profile
+
+    def prepare_context(self, company_short_name: str, user_identifier: str) -> dict:
+        # prepare the context and decide if it needs to be rebuilt
+        # save the generated context in the session context for later use
         if not user_identifier:
-            raise IAToolkitException(IAToolkitException.ErrorType.INVALID_USER,
-                        "No se pudo resolver el identificador del usuario")
+            return {'rebuild_needed': True, 'error': 'Invalid user identifier'}
 
-        company = self.profile_repo.get_company_by_short_name(company_short_name)
-        if not company:
-            raise IAToolkitException(IAToolkitException.ErrorType.INVALID_NAME,
-                               f"Empresa no encontrada: {company_short_name}")
+        # create the company/user context and compute its version
+        final_system_context, user_profile = self._build_context_and_profile(
+            company_short_name, user_identifier)
+
+        # save the user information in the session context
+        # it's needed for the jinja predefined prompts (filtering)
+        self.session_context.save_profile_data(company_short_name, user_identifier, user_profile)
+
+        # calculate the context version
+        current_version = self._compute_context_version_from_string(final_system_context)
 
-        logging.info(f"Inicializando contexto para {company_short_name}/{user_identifier} con modelo {model}  ...")
         try:
-            # 1. clean any previous context for company/user
-            self.session_context.clear_all_context(
-                company_short_name=company_short_name,
-                user_identifier=user_identifier
-            )
+            prev_version = self.session_context.get_context_version(company_short_name, user_identifier)
+        except Exception:
+            prev_version = None
 
-            # 2. get dictionary with user information from company DB
-            # user roles are read at this point from company db
-            user_profile = self.dispatcher.get_user_info(
-                company_name=company_short_name,
-                user_identifier=user_identifier,
-                is_local_user=is_local_user
-            )
+        rebuild_is_needed = not (prev_version and prev_version == current_version and
+                                 self._has_valid_cached_context(company_short_name, user_identifier))
 
-            # add the user logged in to the user_info dictionary
-            user_profile['user_id'] = user_identifier
+        if rebuild_is_needed:
+            # Guardar el contexto preparado y su versión para que `finalize_context_rebuild` los use.
+            self.session_context.save_prepared_context(company_short_name, user_identifier, final_system_context,
+                                                       current_version)
 
-            # save the user information in the session context
-            # it's needed for the jinja predefined prompts (filtering)
-            self.session_context.save_user_session_data(company_short_name, user_identifier, user_profile)
+        return {'rebuild_needed': rebuild_is_needed}
 
-            # 3. render the iatoolkit main system prompt with the company/user information
-            system_prompt_template = self.prompt_service.get_system_prompt()
-            rendered_system_prompt = self.util.render_prompt_from_string(
-                template_string=system_prompt_template,
-                question=None,
-                client_data=user_profile,
-                company=company,
-                service_list=self.dispatcher.get_company_services(company)
-            )
+    def finalize_context_rebuild(self, company_short_name: str, user_identifier: str, model: str = ''):
+
+        # end the initilization, if there is a prepare context send it to llm
+        if not model:
+            model = self.model
+
+        # --- Lógica de Bloqueo ---
+        lock_key = f"lock:context:{company_short_name}/{user_identifier}"
+        if not self.session_context.acquire_lock(lock_key, expire_seconds=60):
+            logging.warning(
+                f"Intento de reconstruir contexto para {user_identifier} mientras ya estaba en progreso. Se omite.")
+            return
+
+        try:
+            start_time = time.time()
+            company = self.profile_repo.get_company_by_short_name(company_short_name)
 
-            # 4. add more company context: schemas, database models, .md files
-            company_specific_context = self.dispatcher.get_company_context(company_name=company_short_name)
+            # get the prepared context and version from the session cache
+            prepared_context, version_to_save = self.session_context.get_and_clear_prepared_context(company_short_name,
+                                                                                                    user_identifier)
+            if not prepared_context:
+                logging.info(
+                    f"No se requiere reconstrucción de contexto para {company_short_name}/{user_identifier}. Finalización rápida.")
+                return
 
-            # 5. merge contexts
-            final_system_context = f"{company_specific_context}\n{rendered_system_prompt}"
+            logging.info(f"Enviando contexto al LLM para {company_short_name}/{user_identifier}...")
+
+            # Limpiar solo el historial de chat y el ID de respuesta anterior
+            self.session_context.clear_llm_history(company_short_name, user_identifier)
 
             if self.util.is_gemini_model(model):
-                # save the initial context as `context_history` (list of messages)
-                context_history = [{"role": "user", "content": final_system_context}]
+                context_history = [{"role": "user", "content": prepared_context}]
                 self.session_context.save_context_history(company_short_name, user_identifier, context_history)
-                logging.info(f"Contexto inicial para Gemini guardado en sesión")
-                return "gemini-context-initialized"
 
             elif self.util.is_openai_model(model):
-
-                # 6. set the company/user context as the initial context for the LLM
                 response_id = self.llm_client.set_company_context(
-                    company=company,
-                    company_base_context=final_system_context,
-                    model=model
+                    company=company, company_base_context=prepared_context, model=model
                 )
-
-                # 7. save response_id in the session context
                 self.session_context.save_last_response_id(company_short_name, user_identifier, response_id)
 
-                logging.info(f"Contexto inicial de company '{company_short_name}/{user_identifier}' ha sido establecido en {int(time.time() - start_time)} seg.")
-                return response_id
+            if version_to_save:
+                self.session_context.save_context_version(company_short_name, user_identifier, version_to_save)
 
+            logging.info(
+                f"Contexto de {company_short_name}/{user_identifier} establecido en {int(time.time() - start_time)} seg.")
         except Exception as e:
-            logging.exception(f"Error al inicializar el contexto del LLM para {company_short_name}: {e}")
+            logging.exception(f"Error en finalize_context_rebuild para {company_short_name}: {e}")
             raise e
+        finally:
+            # --- Liberar el Bloqueo ---
+            self.session_context.release_lock(lock_key)
 
     def llm_query(self,
                   company_short_name: str,
-                  external_user_id: Optional[str] = None,
-                  local_user_id: int = 0,
+                  user_identifier: str,
                   task: Optional[Task] = None,
                   prompt_name: str = None,
                   question: str = '',
                   client_data: dict = {},
                   files: list = []) -> dict:
         try:
-            user_identifier, is_local_user = self.util.resolve_user_identifier(external_user_id, local_user_id)
-            if not user_identifier:
-                return {"error": True,
-                        "error_message": "No se pudo identificar al usuario"}
-
             company = self.profile_repo.get_company_by_short_name(short_name=company_short_name)
             if not company:
                 return {"error": True,
@@ -173,23 +195,19 @@ class QueryService:
                 # get user context
                 previous_response_id = self.session_context.get_last_response_id(company.short_name, user_identifier)
                 if not previous_response_id:
-                    # try to initialize the company/user context
-                    previous_response_id = self.llm_init_context(company.short_name, external_user_id, local_user_id)
-                    if not previous_response_id:
-                        return {'error': True,
-                                "error_message": f"FATAL: No se encontró 'previous_response_id' para '{company.short_name}/{user_identifier}'. La conversación no puede continuar."
-                                }
+                    return {'error': True,
+                            "error_message": f"No se encontró 'previous_response_id' para '{company.short_name}/{user_identifier}'. Reinicia el contexto para continuar."
+                            }
             elif self.util.is_gemini_model(self.model):
                 # check the length of the context_history and remove old messages
                 self._trim_context_history(context_history)
 
-            # get the user data from the session context
-            user_info_from_session = self.session_context.get_user_session_data(company.short_name, user_identifier)
+            # get the user profile data from the session context
+            user_profile = self.profile_service.get_profile_by_identifier(company.short_name, user_identifier)
 
-            # Combinar datos: los datos de la tarea/request tienen prioridad sobre los de la sesión
-            final_client_data = (user_info_from_session or {}).copy()
+            # combine client_data with user_profile
+            final_client_data = (user_profile or {}).copy()
             final_client_data.update(client_data)
-            final_client_data['user_id'] = user_identifier
 
             # Load attached files into the context
             files_context = self.load_files_for_context(files)
@@ -207,7 +225,7 @@ class QueryService:
                     template_string=prompt_content,
                     question=question,
                     client_data=final_client_data,
-                    external_user_id=external_user_id,
+                    user_identifier=user_identifier,
                     company=company,
                 )
 
@@ -254,6 +272,31 @@ class QueryService:
             logging.exception(e)
             return {'error': True, "error_message": f"{str(e)}"}
 
+    def _compute_context_version_from_string(self, final_system_context: str) -> str:
+        # returns a hash of the context string
+        try:
+            return hashlib.sha256(final_system_context.encode("utf-8")).hexdigest()
+        except Exception:
+            return "unknown"
+
+    def _has_valid_cached_context(self, company_short_name: str, user_identifier: str) -> bool:
+        """
+        Verifica si existe un estado de contexto reutilizable en sesión.
+        - OpenAI: last_response_id presente.
+        - Gemini: context_history con al menos 1 mensaje.
+        """
+        try:
+            if self.util.is_openai_model(self.model):
+                prev_id = self.session_context.get_last_response_id(company_short_name, user_identifier)
+                return bool(prev_id)
+            if self.util.is_gemini_model(self.model):
+                history = self.session_context.get_context_history(company_short_name, user_identifier) or []
+                return len(history) >= 1
+            return False
+        except Exception as e:
+            logging.warning(f"Error verificando caché de contexto: {e}")
+            return False
+
     def load_files_for_context(self, files: list) -> str:
         """
         Processes a list of attached files, decodes their content,

iatoolkit/services/tasks_service.py

@@ -101,7 +101,7 @@ class TaskService:
         # call the IA
         response = self.query_service.llm_query(
             task=task,
-            local_user_id=0,
+            user_identifier='task-monitor',
             company_short_name=task.company.short_name,
             prompt_name=task.task_type.name,
             client_data=task.client_data,

iatoolkit/services/user_feedback_service.py

@@ -3,65 +3,101 @@
 #
 # IAToolkit is open source software.
 
-from iatoolkit.repositories.models import UserFeedback
+from iatoolkit.repositories.models import UserFeedback, Company
 from injector import inject
 from iatoolkit.repositories.profile_repo import ProfileRepo
 from iatoolkit.infra.google_chat_app import GoogleChatApp
+from iatoolkit.infra.mail_app import MailApp  # <-- 1. Importar MailApp
 import logging
 
 
 class UserFeedbackService:
     @inject
-    def __init__(self, profile_repo: ProfileRepo, google_chat_app: GoogleChatApp):
+    def __init__(self,
+                 profile_repo: ProfileRepo,
+                 google_chat_app: GoogleChatApp,
+                 mail_app: MailApp):
         self.profile_repo = profile_repo
         self.google_chat_app = google_chat_app
+        self.mail_app = mail_app
+
+    def _send_google_chat_notification(self, space_name: str, message_text: str):
+        """Envía una notificación de feedback a un espacio de Google Chat."""
+        try:
+            chat_data = {
+                "type": "MESSAGE_TRIGGER",
+                "space": {"name": space_name},
+                "message": {"text": message_text}
+            }
+            chat_result = self.google_chat_app.send_message(message_data=chat_data)
+            if not chat_result.get('success'):
+                logging.warning(f"Error al enviar notificación a Google Chat: {chat_result.get('message')}")
+        except Exception as e:
+            logging.exception(f"Fallo inesperado al enviar notificación a Google Chat: {e}")
+
+    def _send_email_notification(self, destination_email: str, company_name: str, message_text: str):
+        """Envía una notificación de feedback por correo electrónico."""
+        try:
+            subject = f"Nuevo Feedback de {company_name}"
+            # Convertir el texto plano a un HTML simple para mantener los saltos de línea
+            html_body = message_text.replace('\n', '<br>')
+            self.mail_app.send_email(to=destination_email, subject=subject, body=html_body)
+        except Exception as e:
+            logging.exception(f"Fallo inesperado al enviar email de feedback: {e}")
+
+    def _handle_notification(self, company: Company, message_text: str):
+        """Lee la configuración de la empresa y envía la notificación al canal correspondiente."""
+        feedback_params = company.parameters.get('user_feedback')
+        if not isinstance(feedback_params, dict):
+            logging.warning(f"No se encontró configuración de 'user_feedback' para la empresa {company.short_name}.")
+            return
+
+        # get channel and destination
+        channel = feedback_params.get('channel')
+        destination = feedback_params.get('destination')
+        if not channel or not destination:
+            logging.warning(f"Configuración 'user_feedback' incompleta para {company.short_name}. Faltan 'channel' o 'destination'.")
+            return
+
+        if channel == 'google_chat':
+            self._send_google_chat_notification(space_name=destination, message_text=message_text)
+        elif channel == 'email':
+            self._send_email_notification(destination_email=destination, company_name=company.short_name, message_text=message_text)
+        else:
+            logging.warning(f"Canal de feedback '{channel}' no reconocido para la empresa {company.short_name}.")
 
     def new_feedback(self,
                      company_short_name: str,
                      message: str,
-                     external_user_id: str = None,
-                     local_user_id: int = 0,
-                     space: str = None,
-                     type: str = None,
+                     user_identifier: str,
                      rating: int = None) -> dict:
         try:
-            # validate company
+            # 1. Validar empresa
             company = self.profile_repo.get_company_by_short_name(company_short_name)
             if not company:
                 return {'error': f'No existe la empresa: {company_short_name}'}
 
-            # send notification to Google Chat
-            chat_message = f"*Nuevo feedback de {company_short_name}*:\n*Usuario:* {external_user_id or local_user_id}\n*Mensaje:* {message}\n*Calificación:* {rating}"
-
-            # TO DO: get the space and type from the input data
-            chat_data = {
-                "type": type,
-                "space": {
-                    "name": space
-                },
-                "message": {
-                    "text": chat_message
-                }
-            }
-
-            chat_result = self.google_chat_app.send_message(message_data=chat_data)
-
-            if not chat_result.get('success'):
-                logging.warning(f"Error al enviar notificación a Google Chat: {chat_result.get('message')}")
+            # 2. Enviar notificación según la configuración de la empresa
+            notification_text = (f"*Nuevo feedback de {company_short_name}*:\n"
+                                 f"*Usuario:* {user_identifier}\n"
+                                 f"*Mensaje:* {message}\n"
+                                 f"*Calificación:* {rating if rating is not None else 'N/A'}")
+            self._handle_notification(company, notification_text)
 
-            # create the UserFeedback object
-            new_feedback = UserFeedback(
+            # 3. Guardar el feedback en la base de datos (independientemente del éxito de la notificación)
+            new_feedback_obj = UserFeedback(
                 company_id=company.id,
                 message=message,
-                local_user_id=local_user_id,
-                external_user_id=external_user_id,
+                user_identifier=user_identifier,
                 rating=rating
             )
-            new_feedback = self.profile_repo.save_feedback(new_feedback)
-            if not new_feedback:
+            saved_feedback = self.profile_repo.save_feedback(new_feedback_obj)
+            if not saved_feedback:
+                logging.error(f"No se pudo guardar el feedback para el usuario {user_identifier} en la empresa {company_short_name}")
                 return {'error': 'No se pudo guardar el feedback'}
 
-            return {'message': 'Feedback guardado correctamente'}
+            return {'success': True, 'message': 'Feedback guardado correctamente'}
 
         except Exception as e:
+            logging.exception(f"Error crítico en el servicio de feedback: {e}")
             return {'error': str(e)}

iatoolkit/services/user_session_context_service.py

@@ -6,80 +6,138 @@
 from iatoolkit.infra.redis_session_manager import RedisSessionManager
 from typing import List, Dict, Optional
 import json
+import logging
 
 
 class UserSessionContextService:
     """
-    Gestiona el contexto de la sesión del usuario, incluyendo el historial
-    de conversación con el LLM y datos de la sesión del usuario.
-
-    Usa RedisSessionManager para persistencia directa en Redis.
+    Gestiona el contexto de la sesión del usuario usando un único Hash de Redis por sesión.
+    Esto mejora la atomicidad y la eficiencia.
     """
 
-    def _get_llm_history_key(self, company_short_name: str, user_identifier: str) -> str:
-        user_identifier = (user_identifier or "").strip()
-        if not user_identifier:
-            return None
-        return f"llm_history:{company_short_name}/{user_identifier}"
-
-    def _get_user_data_key(self, company_short_name: str, user_identifier: str) -> str:
+    def _get_session_key(self, company_short_name: str, user_identifier: str) -> Optional[str]:
+        """Devuelve la clave única de Redis para el Hash de sesión del usuario."""
         user_identifier = (user_identifier or "").strip()
-        if not user_identifier:
+        if not company_short_name or not user_identifier:
             return None
-        return f"user_data:{company_short_name}/{user_identifier}"
+        return f"session:{company_short_name}/{user_identifier}"
 
     def clear_all_context(self, company_short_name: str, user_identifier: str):
-        """Limpia todo el contexto de sesión para un usuario."""
-        self.clear_llm_history(company_short_name, user_identifier)
-        self.clear_user_session_data(company_short_name, user_identifier)
+        """Limpia el contexto del LLM en la sesión para un usuario de forma atómica."""
+        session_key = self._get_session_key(company_short_name, user_identifier)
+        if session_key:
+            # RedisSessionManager.remove(session_key)
+            # 'profile_data' should not be deleted
+            RedisSessionManager.hdel(session_key, 'context_version')
+            RedisSessionManager.hdel(session_key, 'context_history')
+            RedisSessionManager.hdel(session_key, 'last_response_id')
 
     def clear_llm_history(self, company_short_name: str, user_identifier: str):
-        history_key = self._get_llm_history_key(company_short_name, user_identifier)
-        if history_key:
-            RedisSessionManager.remove(history_key)
-
-    def get_last_response_id(self, company_short_name: str, user_identifier: str) -> str:
-        history_key = self._get_llm_history_key(company_short_name, user_identifier)
-        if not history_key:
+        """Limpia solo los campos relacionados con el historial del LLM (ID y chat)."""
+        session_key = self._get_session_key(company_short_name, user_identifier)
+        if session_key:
+            RedisSessionManager.hdel(session_key, 'last_response_id', 'context_history')
+
+    def get_last_response_id(self, company_short_name: str, user_identifier: str) -> Optional[str]:
+        session_key = self._get_session_key(company_short_name, user_identifier)
+        if not session_key:
             return None
-
-        return RedisSessionManager.get(history_key, '')
+        return RedisSessionManager.hget(session_key, 'last_response_id')
 
     def save_last_response_id(self, company_short_name: str, user_identifier: str, response_id: str):
-        user_identifier = (user_identifier or "").strip()
-        history_key = self._get_llm_history_key(company_short_name, user_identifier)
-        if not history_key or not user_identifier:
-            return
-
-        RedisSessionManager.set(history_key, response_id)
+        session_key = self._get_session_key(company_short_name, user_identifier)
+        if session_key:
+            RedisSessionManager.hset(session_key, 'last_response_id', response_id)
 
     def save_context_history(self, company_short_name: str, user_identifier: str, context_history: List[Dict]):
-        history_key = f"chat_history:{company_short_name}/{user_identifier}"
-        if not history_key:
-            return
-        RedisSessionManager.set(history_key, json.dumps(context_history))
+        session_key = self._get_session_key(company_short_name, user_identifier)
+        if session_key:
+            try:
+                history_json = json.dumps(context_history)
+                RedisSessionManager.hset(session_key, 'context_history', history_json)
+            except (TypeError, ValueError) as e:
+                logging.error(f"Error al serializar context_history para {session_key}: {e}")
 
     def get_context_history(self, company_short_name: str, user_identifier: str) -> Optional[List[Dict]]:
-        history_key = f"chat_history:{company_short_name}/{user_identifier}"
-        return RedisSessionManager.get_json(history_key, {})
+        session_key = self._get_session_key(company_short_name, user_identifier)
+        if not session_key:
+            return None
 
-    def save_user_session_data(self, company_short_name: str, user_identifier: str, data: dict):
-        """Guarda un diccionario de datos en la sesión del usuario."""
-        user_identifier = (user_identifier or "").strip()
-        data_key = self._get_user_data_key(company_short_name, user_identifier)
-        if data_key:
-            RedisSessionManager.set_json(data_key, data)
-
-    def get_user_session_data(self, company_short_name: str, user_identifier: str) -> dict:
-        """Recupera el diccionario de datos de la sesión del usuario."""
-        data_key = self._get_user_data_key(company_short_name, user_identifier)
-        if not data_key:
+        history_json = RedisSessionManager.hget(session_key, 'context_history')
+        if not history_json:
+            return []
+
+        try:
+            return json.loads(history_json)
+        except json.JSONDecodeError:
+            return []
+
+    def save_profile_data(self, company_short_name: str, user_identifier: str, data: dict):
+        session_key = self._get_session_key(company_short_name, user_identifier)
+        if session_key:
+            try:
+                data_json = json.dumps(data)
+                RedisSessionManager.hset(session_key, 'profile_data', data_json)
+            except (TypeError, ValueError) as e:
+                logging.error(f"Error al serializar profile_data para {session_key}: {e}")
+
+    def get_profile_data(self, company_short_name: str, user_identifier: str) -> dict:
+        session_key = self._get_session_key(company_short_name, user_identifier)
+        if not session_key:
             return {}
 
-        return RedisSessionManager.get_json(data_key, {})
+        data_json = RedisSessionManager.hget(session_key, 'profile_data')
+        if not data_json:
+            return {}
 
-    def clear_user_session_data(self, company_short_name: str, user_identifier: str):
-        """Limpia los datos de la sesión del usuario."""
-        data_key = self._get_user_data_key(company_short_name, user_identifier)
-        if data_key:
-            RedisSessionManager.remove(data_key)
+        try:
+            return json.loads(data_json)
+        except json.JSONDecodeError:
+            return {}
+
+    def save_context_version(self, company_short_name: str, user_identifier: str, version: str):
+        session_key = self._get_session_key(company_short_name, user_identifier)
+        if session_key:
+            RedisSessionManager.hset(session_key, 'context_version', version)
+
+    def get_context_version(self, company_short_name: str, user_identifier: str) -> Optional[str]:
+        session_key = self._get_session_key(company_short_name, user_identifier)
+        if not session_key:
+            return None
+        return RedisSessionManager.hget(session_key, 'context_version')
+
+    def save_prepared_context(self, company_short_name: str, user_identifier: str, context: str, version: str):
+        """Guarda un contexto de sistema pre-renderizado y su versión, listos para ser enviados al LLM."""
+        session_key = self._get_session_key(company_short_name, user_identifier)
+        if session_key:
+            RedisSessionManager.hset(session_key, 'prepared_context', context)
+            RedisSessionManager.hset(session_key, 'prepared_context_version', version)
+
+    def get_and_clear_prepared_context(self, company_short_name: str, user_identifier: str) -> tuple:
+        """Obtiene el contexto preparado y su versión, y los elimina para asegurar que se usan una sola vez."""
+        session_key = self._get_session_key(company_short_name, user_identifier)
+        if not session_key:
+            return None, None
+
+        pipe = RedisSessionManager.pipeline()
+        pipe.hget(session_key, 'prepared_context')
+        pipe.hget(session_key, 'prepared_context_version')
+        pipe.hdel(session_key, 'prepared_context', 'prepared_context_version')
+        results = pipe.execute()
+
+        # results[0] es el contexto, results[1] es la versión
+        return (results[0], results[1]) if results else (None, None)
+
+    # --- Métodos de Bloqueo ---
+    def acquire_lock(self, lock_key: str, expire_seconds: int) -> bool:
+        """Intenta adquirir un lock. Devuelve True si se adquiere, False si no."""
+        # SET con NX (solo si no existe) y EX (expiración) es una operación atómica.
+        return RedisSessionManager.set(lock_key, "1", ex=expire_seconds, nx=True)
+
+    def release_lock(self, lock_key: str):
+        """Libera un lock."""
+        RedisSessionManager.remove(lock_key)
+
+    def is_locked(self, lock_key: str) -> bool:
+        """Verifica si un lock existe."""
+        return RedisSessionManager.exists(lock_key)