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

{services → iatoolkit/services}/query_service.py

@@ -1,25 +1,27 @@
 # Copyright (c) 2024 Fernando Libedinsky
-# Producto: IAToolkit
-# Todos los derechos reservados.
-# En trámite de registro en el Registro de Propiedad Intelectual de Chile.
-
-from infra.llm_client import llmClient
-from repositories.document_repo import DocumentRepo
-from repositories.profile_repo import ProfileRepo
-from services.document_service import DocumentService
-from repositories.llm_query_repo import LLMQueryRepo
-from repositories.models import Task
-from services.dispatcher_service import Dispatcher
-from services.prompt_manager_service import PromptService
-from services.user_session_context_service import UserSessionContextService
-from common.util import Utility
-from common.exceptions import IAToolkitException
+# Product: IAToolkit
+#
+# 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
+from iatoolkit.services.user_session_context_service import UserSessionContextService
+from iatoolkit.common.util import Utility
+from iatoolkit.common.exceptions import IAToolkitException
 from injector import inject
 import base64
 import logging
-from typing import Optional, TYPE_CHECKING
+from typing import Optional
 import json
 import time
+import hashlib
 import os
 
 
@@ -29,6 +31,7 @@ class QueryService:
     @inject
     def __init__(self,
                  llm_client: llmClient,
+                 profile_service: ProfileService,
                  document_service: DocumentService,
                  document_repo: DocumentRepo,
                  llmquery_repo: LLMQueryRepo,
@@ -38,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
@@ -48,113 +52,132 @@ class QueryService:
         self.session_context = session_context
         self.llm_client = llm_client
 
-        # Obtener el modelo de las variables de entorno
+        # get the model from the environment variable
         self.model = os.getenv("LLM_MODEL", "")
         if not self.model:
             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)
+
+        # 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)
 
-        # Validate the user and company
-        user_identifier, is_local_user = self.util.resolve_user_identifier(external_user_id, local_user_id)
+        # 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 = ''):
 
-            # 4. add more company context: schemas, database models, .md files
-            company_specific_context = self.dispatcher.get_company_context(company_name=company_short_name)
+        # end the initilization, if there is a prepare context send it to llm
+        if not model:
+            model = self.model
 
-            # 5. merge contexts
-            final_system_context = f"{company_specific_context}\n{rendered_system_prompt}"
+        # --- 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)
+
+            # 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
+
+            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,
@@ -172,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)
@@ -206,18 +225,12 @@ 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,
                 )
 
-            # client profile
-            client_profile = ''
-            if final_client_data.get('client_identity'):
-                client_profile = f"cliente sobre el cual se esta consultando se identifica como ´client_identity´ y tiene el valor: {final_client_data.get('client_identity')}"
-
-
             # This is the final user-facing prompt for this specific turn
-            user_turn_prompt = f"{main_prompt}\n{client_profile}\n{files_context}"
+            user_turn_prompt = f"{main_prompt}\n{files_context}"
             if not prompt_name:
                 user_turn_prompt += f"\n### La pregunta que debes responder es: {question}"
             else:
@@ -259,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,

{services → iatoolkit/services}/search_service.py

@@ -1,10 +1,10 @@
 # Copyright (c) 2024 Fernando Libedinsky
-# Producto: IAToolkit
-# Todos los derechos reservados.
-# En trámite de registro en el Registro de Propiedad Intelectual de Chile.
+# Product: IAToolkit
+#
+# IAToolkit is open source software.
 
-from repositories.vs_repo import VSRepo
-from repositories.document_repo import DocumentRepo
+from iatoolkit.repositories.vs_repo import VSRepo
+from iatoolkit.repositories.document_repo import DocumentRepo
 from injector import inject
 
 
@@ -18,6 +18,22 @@ class SearchService:
         self.doc_repo = doc_repo
 
     def search(self, company_id:  int, query: str, metadata_filter: dict = None) -> str:
+        """
+        Performs a semantic search for a given query within a company's documents.
+
+        This method queries the vector store for relevant documents based on the
+        provided query text. It then constructs a formatted string containing the
+        content of the retrieved documents, which can be used as context for an LLM.
+
+        Args:
+            company_id: The ID of the company to search within.
+            query: The text query to search for.
+            metadata_filter: An optional dictionary to filter documents by their metadata.
+
+        Returns:
+            A string containing the concatenated content of the found documents,
+            formatted to be used as a context.
+        """
         document_list = self.vs_repo.query(company_id=company_id,
                                            query_text=query,
                                            metadata_filter=metadata_filter)

{services → iatoolkit/services}/sql_service.py

@@ -1,14 +1,15 @@
 # Copyright (c) 2024 Fernando Libedinsky
-# Producto: IAToolkit
-# Todos los derechos reservados.
-# En trámite de registro en el Registro de Propiedad Intelectual de Chile.
+# Product: IAToolkit
+#
+# IAToolkit is open source software.
 
-from repositories.database_manager import DatabaseManager
-from common.util import Utility
+from iatoolkit.repositories.database_manager import DatabaseManager
+
+from iatoolkit.common.util import Utility
 from sqlalchemy import text
 from injector import inject
 import json
-from common.exceptions import IAToolkitException
+from iatoolkit.common.exceptions import IAToolkitException
 
 
 class SqlService:
@@ -17,6 +18,23 @@ class SqlService:
         self.util = util
 
     def exec_sql(self, db_manager: DatabaseManager, sql_statement: str) -> str:
+        """
+        Executes a raw SQL statement and returns the result as a JSON string.
+
+        This method takes a DatabaseManager instance and a SQL query, executes it
+        against the database, and fetches all results. The results are converted
+        into a list of dictionaries, where each dictionary represents a row.
+        This list is then serialized to a JSON string.
+        If an exception occurs during execution, the transaction is rolled back,
+        and a custom IAToolkitException is raised.
+
+        Args:
+            db_manager: The DatabaseManager instance to get the database session from.
+            sql_statement: The raw SQL statement to be executed.
+
+        Returns:
+            A JSON string representing the list of rows returned by the query.
+        """
         try:
             # here the SQL is executed
             result = db_manager.get_session().execute(text(sql_statement))

{services → iatoolkit/services}/tasks_service.py

@@ -1,15 +1,15 @@
 # Copyright (c) 2024 Fernando Libedinsky
-# Producto: IAToolkit
-# Todos los derechos reservados.
-# En trámite de registro en el Registro de Propiedad Intelectual de Chile.
+# Product: IAToolkit
+#
+# IAToolkit is open source software.
 
 from injector import inject
-from repositories.models import Task, TaskStatus
-from services.query_service import QueryService
-from repositories.tasks_repo import TaskRepo
-from repositories.profile_repo import ProfileRepo
-from infra.call_service import CallServiceClient
-from common.exceptions import IAToolkitException
+from iatoolkit.repositories.models import Task, TaskStatus
+from iatoolkit.services.query_service import QueryService
+from iatoolkit.repositories.tasks_repo import TaskRepo
+from iatoolkit.repositories.profile_repo import ProfileRepo
+from iatoolkit.infra.call_service import CallServiceClient
+from iatoolkit.common.exceptions import IAToolkitException
 from datetime import datetime
 from werkzeug.utils import secure_filename
 
@@ -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

@@ -0,0 +1,103 @@
+# Copyright (c) 2024 Fernando Libedinsky
+# Product: IAToolkit
+#
+# IAToolkit is open source software.
+
+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,
+                 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,
+                     user_identifier: str,
+                     rating: int = None) -> dict:
+        try:
+            # 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}'}
+
+            # 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)
+
+            # 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,
+                user_identifier=user_identifier,
+                rating=rating
+            )
+            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 {'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)}