## https://sploitus.com/exploit?id=8BE67582-8569-56D1-9483-7D3DA68FAB75
# LangExtract POC - Arquitectura Hexagonal
Sistema de extracción de datos de documentos PDF usando `langextract` con arquitectura hexagonal completa.
## 🏗️ Arquitectura
La aplicación implementa una **arquitectura hexagonal** (también conocida como arquitectura de puertos y adaptadores) que separa claramente las responsabilidades:
```
src/
├── domain/ # 🎯 Capa de Dominio (Lógica de Negocio)
│ ├── entities/ # Entidades del dominio
│ ├── value_objects/ # Objetos de valor
│ ├── repositories/ # Interfaces de repositorios
│ └── services/ # Servicios del dominio
├── application/ # 🔄 Capa de Aplicación (Casos de Uso)
│ ├── use_cases/ # Casos de uso
│ ├── dtos/ # Objetos de transferencia de datos
│ └── ports/ # Puertos (interfaces)
├── infrastructure/ # 🔌 Capa de Infraestructura (Adaptadores)
│ ├── adapters/ # Adaptadores externos
│ ├── repositories/ # Implementaciones de repositorios
│ └── external_services/ # Servicios externos
└── examples/ # 📚 Ejemplos de Uso
├── basic/ # Ejemplos básicos
└── advanced/ # Ejemplos avanzados
```
## 🚀 Características
- ✅ **Arquitectura Hexagonal** completa con separación de capas
- ✅ **Inyección de Dependencias** manual y clara
- ✅ **Interfaces y Abstracciones** bien definidas
- ✅ **Configuración Externa** en archivos JSON
- ✅ **Esquemas de Validación** JSON Schema
- ✅ **Ejemplos de Entrenamiento** separados por tipo de documento
- ✅ **Logging Estructurado** con diferentes niveles
- ✅ **Manejo de Errores** robusto
- ✅ **Métricas de Confianza** automáticas
- ✅ **Procesamiento por Lotes** para múltiples documentos
## 📦 Instalación
1. **Clonar el repositorio:**
```bash
git clone
cd langextract-poc
```
2. **Instalar dependencias:**
```bash
poetry install
```
3. **Activar el entorno virtual:**
```bash
poetry shell
```
## 🎯 Uso
### Uso Básico
```bash
# Extraer datos de un PDF
python src/main.py --pdf data/input/declaracion_impo.pdf --output data/output/result.json
# Con nivel de logging específico
python src/main.py --pdf data/input/declaracion_impo.pdf --log-level DEBUG
```
### Ejemplos Programáticos
#### Ejemplo Básico
```bash
python src/examples/basic/simple_extraction.py
```
#### Ejemplo Avanzado (Procesamiento por Lotes)
```bash
python src/examples/advanced/batch_extraction.py
```
### Uso como Librería
```python
import asyncio
from src.main import LangExtractApplication
from pathlib import Path
async def extract_data():
app = LangExtractApplication()
result = await app.extract_from_pdf(
pdf_path=Path("data/input/declaracion_impo.pdf"),
output_path=Path("data/output/result.json")
)
print(result["extracted_data"])
asyncio.run(extract_data())
```
## 🔧 Configuración
### Configuración de Extracción (`config/extraction_config.json`)
```json
{
"models": {
"default": "gpt-4o-mini",
"alternatives": ["gpt-3.5-turbo", "gpt-4"]
},
"extraction": {
"max_tokens": 4000,
"temperature": 0.1,
"timeout": 30
},
"validation": {
"required_fields": ["numero_declaracion", "fecha", "importador", "valor_total"],
"field_types": {
"numero_declaracion": "string",
"fecha": "date",
"valor_total": "number"
}
}
}
```
### Esquemas de Validación (`data/schemas/`)
Los esquemas JSON definen la estructura esperada de los datos extraídos:
- `declaracion_schema.json`: Esquema para declaraciones de importación
### Ejemplos de Entrenamiento (`config/`)
Los ejemplos de entrenamiento están organizados por tipo de documento:
- `examples_declaracion_importacion.json`: Ejemplos para declaraciones de importación
## 🏛️ Componentes Principales
### Capa de Dominio
#### Entidades
- **`Document`**: Representa un documento con metadatos y contenido
- **`ExtractionResult`**: Resultado de una extracción con métricas de confianza
#### Value Objects
- **`DocumentType`**: Tipos de documentos soportados
- **`DocumentStatus`**: Estados del ciclo de vida del documento
- **`ExtractionStatus`**: Estados del proceso de extracción
- **`ConfidenceLevel`**: Niveles de confianza (LOW, MEDIUM, HIGH, VERY_HIGH)
#### Servicios
- **`ExtractionService`**: Interfaz para servicios de extracción
- **`DocumentValidationService`**: Validación de documentos
### Capa de Aplicación
#### Casos de Uso
- **`ExtractDocumentDataUseCase`**: Orquesta el proceso completo de extracción
#### DTOs
- **`ExtractionRequest`**: Solicitud de extracción
- **`ExtractionResponse`**: Respuesta con datos extraídos
### Capa de Infraestructura
#### Adaptadores
- **`LangExtractAdapter`**: Integración con langextract
- **`JsonConfigAdapter`**: Configuración desde archivos JSON
#### Repositorios
- **`MemoryDocumentRepository`**: Almacenamiento en memoria para documentos
- **`MemoryExtractionRepository`**: Almacenamiento en memoria para extracciones
## 📊 Métricas y Monitoreo
El sistema incluye métricas automáticas:
- **Tiempo de procesamiento**
- **Puntaje de confianza** (0.0 - 1.0)
- **Nivel de confianza** (LOW, MEDIUM, HIGH, VERY_HIGH)
- **Errores de validación**
- **Completitud de campos críticos**
## 🔍 Validación
### Validación de Documentos
- Formato de archivo (PDF, DOCX, etc.)
- Tamaño máximo de archivo
- Integridad del contenido
### Validación de Datos Extraídos
- Esquemas JSON Schema
- Campos requeridos
- Tipos de datos
- Rangos de valores
## 🚦 Estados y Flujos
### Estados del Documento
```
UPLOADED → PROCESSING → PROCESSED
↓ ↓ ↓
ERROR ←─────────────→ ARCHIVED
```
### Estados de Extracción
```
PENDING → IN_PROGRESS → COMPLETED → VALIDATED
↓ ↓ ↓ ↓
FAILED ←─────────────→ REJECTED ←─────┘
```
## 🧪 Testing
Para ejecutar los ejemplos y verificar el funcionamiento:
```bash
# Ejemplo básico
python src/examples/basic/simple_extraction.py
# Ejemplo avanzado
python src/examples/advanced/batch_extraction.py
# Aplicación principal
python src/main.py --pdf data/input/declaracion_impo.pdf
```
## 📁 Estructura de Archivos
```
langextract-poc/
├── README.md
├── pyproject.toml
├── poetry.lock
├── config/ # Configuración
│ ├── extraction_config.json
│ └── examples_declaracion_importacion.json
├── data/ # Datos
│ ├── input/ # Archivos de entrada
│ ├── output/ # Resultados
│ └── schemas/ # Esquemas de validación
├── src/ # Código fuente
│ ├── __init__.py
│ ├── main.py # Punto de entrada principal
│ ├── domain/ # Capa de dominio
│ ├── application/ # Capa de aplicación
│ ├── infrastructure/ # Capa de infraestructura
│ └── examples/ # Ejemplos de uso
└── code/ # Código original (referencia)
└── langextract-poc.py
```
## 🔄 Extensibilidad
La arquitectura hexagonal facilita la extensión del sistema:
### Agregar Nuevos Tipos de Documentos
1. Crear nuevos ejemplos en `config/examples_.json`
2. Definir esquema en `data/schemas/_schema.json`
3. Agregar tipo a `DocumentType` enum
### Agregar Nuevos Adaptadores
1. Implementar la interfaz `ExtractionService`
2. Registrar en la configuración de dependencias
3. Usar inyección de dependencias
### Agregar Nuevos Repositorios
1. Implementar interfaces de repositorio
2. Configurar en la aplicación principal
3. Mantener compatibilidad con casos de uso existentes
## 🤝 Contribución
1. Fork el proyecto
2. Crear una rama para tu feature (`git checkout -b feature/AmazingFeature`)
3. Commit tus cambios (`git commit -m 'Add some AmazingFeature'`)
4. Push a la rama (`git push origin feature/AmazingFeature`)
5. Abrir un Pull Request
## 📄 Licencia
Este proyecto está bajo la Licencia MIT - ver el archivo [LICENSE](LICENSE) para detalles.