docs: Enhance docstrings across multiple modules for improved clarity and consistency, detailing parameters, return values, and exceptions. Remove obsolete test files related to LLM and PDF utilities.

core/pdf_utils.py

@@ -32,9 +32,21 @@ def pdf_to_images_bs64(
   thread_count: int = 10,
   poppler_path: str | None = None,
 ) -> List[str]:
-  """Convierte un PDF a una lista de PNGs en base64.
+  """
+  Convierte un archivo PDF completo a una lista de imágenes PNG en base64.
 
-  Usa pdf2image + Poppler. Lanza ValueError si una imagen no valida.
+  Args:
+      pdf_path: Ruta al archivo PDF.
+      validate: Si es True, intenta abrir cada imagen generada para verificar su integridad.
+      dpi: Resolución de la imagen (puntos por pulgada).
+      thread_count: Número de hilos para la conversión paralela de páginas.
+      poppler_path: Ruta personalizada a los binarios de Poppler (opcional).
+
+  Returns:
+      Lista de strings con las imágenes codificadas en base64.
+
+  Raises:
+      ValueError: Si la validación de alguna imagen falla.
   """
   poppler_bin = _resolve_poppler(poppler_path)
   t0 = time.time()
@@ -60,7 +72,16 @@ def pdf_to_images_bs64(
 
 
 def get_pdf_num_pages(pdf_path: str, poppler_path: str | None = None) -> int:
-  """Devuelve el número de páginas de un PDF usando pdfinfo_from_path."""
+  """
+  Obtiene el número total de páginas de un PDF.
+
+  Args:
+      pdf_path: Ruta al archivo PDF.
+      poppler_path: Ruta personalizada a los binarios de Poppler (opcional).
+
+  Returns:
+      Número de páginas (0 si ocurre un error).
+  """
   info = pdfinfo_from_path(pdf_path, poppler_path=_resolve_poppler(poppler_path))
   try:
     return int(info.get('Pages') or info.get('pages') or 0)
@@ -79,9 +100,21 @@ def pdf_pages_to_images_bs64(
   thread_count: int = 10,
   poppler_path: str | None = None,
 ) -> List[str]:
-  """Convierte un rango [first_page, last_page] (1-indexed, inclusivo) a PNGs base64.
+  """
+  Convierte un rango específico de páginas de un PDF a imágenes base64.
 
-  Opcionalmente aplica escala de grises y omite validación para acelerar.
+  Args:
+      pdf_path: Ruta al archivo PDF.
+      first_page: Índice de la primera página (1-indexed).
+      last_page: Índice de la última página (inclusivo).
+      dpi: Resolución de la imagen.
+      grayscale: Si es True, convierte las imágenes a escala de grises para ahorrar ancho de banda/tokens.
+      validate: Si es True, verifica la integridad de las imágenes generadas.
+      thread_count: Número de hilos para procesamiento paralelo.
+      poppler_path: Ruta personalizada a Poppler.
+
+  Returns:
+      Lista de imágenes en base64.
   """
   poppler_bin = _resolve_poppler(poppler_path)
   t0 = time.time()
@@ -119,12 +152,17 @@ def pdf_pages_to_images_bs64(
   return resultados
 
 def tiff_to_images_bs64(tiff_path: str, validate: bool = True, pages_range: Optional[Tuple[int, int]] = (2, 3)) -> List[str]:
-  """Convierte un TIFF multipágina a PNGs en base64.
+  """
+  Convierte un archivo TIFF multipágina a una lista de imágenes PNG en base64.
 
-  Por defecto, procesa un rango de páginas inclusivo cuando se especifica
-  `pages_range` como `(inicio, fin)`, usando índices 1-based. Use None para
-  procesar todas las páginas. Puede pasar `None` en uno de los extremos para
-  indicar “sin inicio” o “sin fin”.
+  Args:
+      tiff_path: Ruta al archivo TIFF.
+      validate: Si es True, verifica la integridad de las imágenes generadas.
+      pages_range: Tupla (inicio, fin) de páginas a procesar (1-indexed, inclusivo).
+                  Use None para procesar todas las páginas.
+
+  Returns:
+      Lista de imágenes en base64.
   """
   resultados: List[str] = []
   t0 = time.time()
@@ -166,11 +204,22 @@ def document_to_images_bs64(
   tiff_page_range: Optional[Tuple[int, int]] = None,
   poppler_path: str | None = None,
 ) -> List[str]:
-  """Puerta de entrada: decide conversión según la extensión (.pdf, .tif/.tiff).
+  """
+  Función unificada para convertir documentos (PDF o TIFF) a imágenes base64.
 
-  `tiff_page_range` permite indicar un rango explícito (inicio, fin) 1-based
-  para TIFF. Si es None, se usa `tiff_pages` como valor por defecto.
-  `poppler_path` se pasa a las funciones PDF; si es None se usa el default del proyecto.
+  Detecta automáticamente el formato por la extensión del archivo.
+
+  Args:
+      path: Ruta al archivo.
+      validate: Si es True, valida las imágenes generadas.
+      dpi: Resolución para archivos PDF.
+      thread_count: Hilos paralelos para archivos PDF.
+      tiff_pages: Páginas TIFF por defecto si tiff_page_range es None.
+      tiff_page_range: Rango explícito de páginas para TIFF (inicio, fin).
+      poppler_path: Ruta personalizada a Poppler para PDFs.
+
+  Returns:
+      Lista de imágenes en base64.
   """
   ext = os.path.splitext(path)[1].lower()
   if ext == ".pdf":