feat: Implement the initial IPSExtractor project structure, including application logic, GUI, core utilities, and documentation.

2026-02-23 09:24:06 -05:00
commit 69debb1c93
49 changed files with 7385 additions and 0 deletions
@@ -0,0 +1,53 @@
+# `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
+```python
+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",
+)
+```
+
+