IPSExtractor

Sistema avanzado para la extracción y procesamiento de datos de facturas médicas (IPS) utilizando modelos de Inteligencia Artificial Multimodal (LLMs). Convierte documentos (PDF/TIFF) a imágenes, extrae información estructurada, la normaliza y la exporta a CSV.

🚀 Características Principales

• Extracción Multimodal: Usa modelos de visión (como qwen2.5vl) vía API compatible con OpenAI/Ollama para "leer" documentos como imágenes.
• Procesamiento Inteligente:
  • Conversión automática de PDF/TIFF a imágenes optimizadas.
  • Descubrimiento automático de documentos por radicado (prioriza TIFF).
  • Normalización de Datos: Estandarización de salidas JSON mediante post-procesamiento con LLM.
• Gestión Robusta:
  • Sistema de Logs Estructurados (JSON) y salida en consola coloreada para fácil depuración.
  • Estimación de costos y tokens antes de ejecutar.
  • Manejo de reintentos y "fallback" automático (reducción de DPI) en caso de fallos.
• Interfaz Gráfica (GUI):
  • Selección interactiva de carpetas y configuración.
  • Selector visual de campos a extraer (Schema Builder).
  • Barra de progreso y logs en tiempo real.
• Exportación: Generación incremental de reportes CSV (una fila por ítem de factura).

📋 Requisitos

• Python 3.10+
• Poppler (para procesar PDFs):
  • Windows: Incluido en dependencies/poppler-24.08.0/Library/bin.
  • Linux/Mac: Instalar vía gestor de paquetes (sudo apt install poppler-utils).
• Acceso a LLM: Un servidor Ollama corriendo localmente o acceso a una API compatible con OpenAI.

🛠️ Instalación

1. Clonar el repositorio y crear entorno virtual:

   python -m venv .venv
   # Windows
   .venv\Scripts\activate
   # Linux/Mac
   source .venv/bin/activate
   

2. Instalar dependencias:

   pip install -r requirements.txt
   

⚙️ Configuración (.env)

La configuración se gestiona mediante variables de entorno. Crea un archivo .env en la raíz con los siguientes parámetros (ajusta según tu entorno):

# Configuración del Modelo Extractor
EXTRACTOR_BASE_URL=http://10.8.0.4:11434/v1
EXTRACTOR_API_KEY=ollama
EXTRACTOR_MODEL=qwen2.5vl:32b
EXTRACTOR_TIMEOUT_S=120

# Configuración de Procesamiento de Imagen
PDF_DPI=600
PDF_THREAD_COUNT=10
TIFF_PAGES=(2,3)

# Configuración de Rutas y Salida
POPPLER_PATH=dependencies/poppler-24.08.0/Library/bin
CSV_DELIMITER=|

🖥️ Uso de la Aplicación

Ejecuta el punto de entrada principal:

python gui_main.py

Flujo de Trabajo en GUI:

1. Pestaña "Procesar":
   • Selecciona la carpeta raíz que contiene las subcarpetas de los radicados.
   • (Opcional) Define keywords para filtrar archivos específicos.
   • Selecciona dónde guardar el CSV de salida.
   • Haz clic en "Procesar".
   • Si es la primera vez: Se abrirá un selector de campos para que elijas qué datos extraer basándose en el primer documento detectado.
2. Pestaña "Configuración":
   • Permite ajustar dinámicamente la URL de la API o el modelo sin reiniciar la aplicación.

🏗️ Arquitectura del Código

El proyecto sigue una arquitectura modular para facilitar el mantenimiento y la escalabilidad:

Capa de Aplicación (application/):

• service.py: Fachada principal (InvoiceProcessingService). Punto de entrada único para la lógica de negocio.
• batch_processor.py: Motor de procesamiento masivo. Maneja la iteración de radicados, reportes de progreso y orquestación multi-hilo.
• estimator.py: Lógica para calcular costos estimados y uso de tokens antes de lanzar procesos largos.
• strategies.py: Implementación del cliente LLM (OllamaExtractor) y patrones de extracción.
• normalizer.py: Servicio de normalización de datos JSON post-extracción para asegurar consistencia en el esquema.
• csv_manager.py: Manejador thread-safe para la escritura incremental de archivos CSV.
• logging_config.py: Configuración avanzada de logging (salida JSON para máquinas y colores para humanos).
• file_discovery.py: Utilidades para exploración eficiente del sistema de archivos.

Capa Core (core/):

• pdf_utils.py: Wrapper sobre Poppler para la rasterización de documentos PDF/TIFF.
• text_utils.py: Herramientas de limpieza de texto y extracción robusta de bloques JSON.
• csv_utils.py: Utilidades puras para aplanamiento de diccionarios anidados y generación de cabeceras.

Capa GUI (gui/):

• Interfaz construida con customtkinter, implementando un patrón MVC básico (View, Controller).

📊 Logs y Depuración

El sistema genera logs detallados en la carpeta logs/ para auditoría y depuración:

• ips_extractor.log: Log principal de la aplicación (formato JSON estructurado).
• llm.log: Trazabilidad específica de las interacciones con el LLM (prompts y respuestas).
• api_calls.log: Métricas de uso de API y tokens.

Además, la salida por consola está optimizada con colores para una lectura rápida del estado del procesamiento.

📝 Licencia

Uso interno. Ajuste según sus necesidades.