IPSExtractor/docs/application/service.md

application/service.py

Propósito

Fachada de alto nivel para procesar facturas:

• Convierte documentos (PDF/TIFF) a imágenes base64 según configuración.
• Llama a una estrategia de extracción multimodal (OpenAI/Ollama compatible).
• Construye un esquema a partir del primer documento y permite seleccionar campos.
• Escribe CSV incrementalmente respetando la selección de paths.

API pública

InvoiceProcessingService.extract_full_from_pdf(pdf_path, instruction=None) -> dict

Extrae JSON completo desde un documento. Selecciona instrucción por defecto del perfil invoice si no se provee y aplica fallback (DPI reducido, límite de páginas) ante fallos del backend.

Parámetros:

• pdf_path: ruta al documento.
• instruction: instrucción (prompt) opcional.

InvoiceProcessingService.build_schema_from_first(pdf_path, ...) -> (schema, data)

Construye un esquema de rutas a partir del primer documento y devuelve también los datos extraídos.

InvoiceProcessingService.process_root_with_field_selection(root_path, keywords=None, *, doc_types=None, fields=None, on_progress=None, csv_output_path=None, csv_header_override=None, instruction_override=None, on_usage=None, alias_map=None) -> list[dict]

Procesa radicados en un directorio aplicando una selección de campos. Si fields es None, devuelve un objeto con _needs_fields para que el llamador abra el selector de campos.

Selección de archivos por keywords/patrones

• En modo sencillo (keywords), las palabras se interpretan como:
  • Texto sin */?: coincide si el nombre de archivo contiene ese texto (case-insensitive).
  • Patrón con */?: se evalúa usando semántica tipo Windows (*_1, *_OK?.pdf, etc.).
• En modo multi-documento (doc_types), cada tipo tiene su propio keyword/patrón con la misma semántica.
• Si el patrón no incluye extensión, se aplica sobre el nombre sin extensión y solo se consideran .pdf, .tif, .tiff.
• Si incluye una extensión válida (por ejemplo .pdf en *_OK?.pdf), se respeta exactamente esa extensión.

Consideraciones

• La escritura CSV respeta el orden de csv_header_override si se proporciona.
• Se incluyen logs detallados de tiempos y tamaños para diagnosticar problemas.

Ejemplos

from application.service import InvoiceProcessingService
from application.strategies import OllamaExtractor

svc = InvoiceProcessingService(OllamaExtractor())
schema, first = svc.build_schema_from_first("ejemplo.pdf")
resultados = svc.process_root_with_field_selection(
    root_path="C:/facturas",
    keywords=["FACTURA"],
    fields=["radicado", "items/*/codigo", "items/*/cantidad"],
    csv_output_path="salida.csv",
)