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.

application/preclassification.py

@@ -16,12 +16,27 @@ from core.pdf_utils import document_to_images_bs64
 logger = logging.getLogger(__name__)
 
 class PreclassificationService:
+    """
+    Servicio para la preclasificación masiva de documentos.
+    
+    Permite identificar si un documento cumple con ciertos criterios (patterns)
+    y extraer información clave para organizar los archivos físicamente en carpetas.
+    """
     def __init__(self, extractor: OllamaExtractor):
         self.extractor = extractor
         self.db = DatabaseManager()
 
     def export_to_excel(self, run_id: int, output_path: str) -> bool:
-        """Exporta los resultados de una ejecución a Excel (xlsx) o CSV."""
+        """
+        Exporta los resultados de una ejecución de preclasificación a Excel o CSV.
+
+        Args:
+            run_id: ID de la ejecución en la base de datos.
+            output_path: Ruta del archivo de salida (.xlsx o .csv).
+
+        Returns:
+            True si la exportación fue exitosa, False si no hay datos.
+        """
         try:
             results = self.db.get_run_results(run_id)
             if not results:
@@ -74,8 +89,15 @@ class PreclassificationService:
 
     def organize_files(self, run_id: int, base_output_path: str) -> tuple[int, int]:
         """
-        Organiza los archivos MATCH en carpetas jerárquicas.
-        Devuelve (total_copiados, total_errores).
+        Copia físicamente los archivos que hicieron 'MATCH' a una nueva estructura de carpetas.
+        La jerarquía se determina automáticamente basada en los valores extraídos.
+
+        Args:
+            run_id: ID de la ejecución.
+            base_output_path: Directorio donde se creará la nueva estructura.
+
+        Returns:
+            Tupla (total_copiados, total_errores).
         """
         run = self.db.get_run(run_id)
         mode = "radicados"
@@ -173,7 +195,7 @@ class PreclassificationService:
         return count_ok, count_err
 
     def _sanitize_filename(self, name: str) -> str:
-        """Limpia caracteres inválidos para rutas de archivo."""
+        """Limpia caracteres inválidos para rutas de archivo en Windows/Linux."""
         # Reemplazar caracteres no alfanuméricos (excepto espacio, guion, punto)
         clean = re.sub(r'[\\/*?:"<>|]', "", name)
         clean = clean.replace("\n", " ").replace("\r", "").strip()
@@ -191,8 +213,18 @@ class PreclassificationService:
         mode: str = "radicados" # "radicados" | "general"
     ) -> int:
         """
-        Ejecuta el flujo de preclasificación.
-        Devuelve el run_id.
+        Ejecuta el flujo completo de preclasificación sobre un directorio.
+
+        Args:
+            root_path: Directorio con los documentos.
+            patterns: Reglas de validación (ej. buscar NIT, buscar Fecha).
+            target_info: Filtro de archivos por nombre/patrón.
+            page_range: Rango de páginas a procesar por documento.
+            on_progress: Callback para reportar avance a la GUI.
+            mode: 'radicados' (carpetas) o 'general' (archivos sueltos).
+
+        Returns:
+            ID de la ejecución (run_id) generada.
         """
         # 1. Crear Run en BD
         mode = str(mode or "radicados").strip().lower()