# `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",
)
```