spharagusnet 0.2.0__tar.gz

spharagusnet-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 J. Sebastian Miño
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spharagusnet-0.2.0/PKG-INFO

@@ -0,0 +1,394 @@
+Metadata-Version: 2.4
+Name: spharagusnet
+Version: 0.2.0
+Summary: Neural document OCR for Chilean territorial planning documents
+Author: J. Sebastian Miño
+License: MIT
+Project-URL: Homepage, https://github.com/jsmdev/spharagusnet
+Project-URL: Repository, https://github.com/jsmdev/spharagusnet
+Project-URL: Issues, https://github.com/jsmdev/spharagusnet/issues
+Keywords: ocr,neural-network,chile,urban-planning,document-extraction
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Text Processing :: General
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Pillow>=10.0.0
+Requires-Dist: pytesseract>=0.3.13
+Requires-Dist: pymupdf>=1.24.0
+Requires-Dist: torch>=2.2.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: tqdm>=4.66.0
+Provides-Extra: train
+Requires-Dist: pdfplumber>=0.11.0; extra == "train"
+Requires-Dist: PyPDF2>=3.0.0; extra == "train"
+Requires-Dist: python-Levenshtein>=0.25.0; extra == "train"
+Requires-Dist: pandas>=2.0.0; extra == "train"
+Requires-Dist: numpy>=1.26.0; extra == "train"
+Provides-Extra: dev
+Requires-Dist: spharagusnet[train]; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# SpharagusNet
+
+![SpharagusNet Logo](ChatGPT%20Image%20Mar%2011,%202026,%2002_30_29%20AM.png)
+
+## Sobre el Nombre
+
+**SpharagusNet** combina dos figuras mitológicas que representan las capacidades del sistema:
+
+- **Sphinx** (Esfinge): La criatura que lee enigmas y extrae significado. Representa la capacidad del sistema para procesar documentos complejos y extraer información relevante de textos escaneados, interpretando el contenido legal y normativo de los instrumentos de planificación territorial.
+
+- **Argus** (Argos): El gigante de 100 ojos que todo lo ve. Representa la capacidad del sistema para observar y procesar múltiples fuentes de información simultáneamente.
+
+Juntos, **SpharagusNet** es un sistema que observa todo (Argus) y extrae significado (Sphinx) de los documentos de planificación territorial de Chile.
+
+## ¿Por Qué no Solo OCR Convencional?
+
+La diferencia es fundamental. **Tesseract OCR puro** extrae todo texto de una imagen: encabezados, números de página, pies, metadata, contenido real... **todo mezclado.**
+
+Con documentos escaneados complejos, el resultado es **90% ruido, 10% contenido útil**.
+
+```
+┌─────────────────────────────────────────────┐
+│ OCR CONVENCIONAL (Tesseract solo)           │
+├─────────────────────────────────────────────┤
+│ ES ÓN = PATA > Me A A E A AS               │
+│ 1 A sas "e . Cr, - . MN y                  │
+│ Ps CINARIO SU TOC NTNURLICADE CHILE        │
+│ ; A Maries £5 de Septiémbre de 1990 Pág   │
+│ ... (caracteres aleatorios, basura)        │
+└─────────────────────────────────────────────┘
+❌ Inutilizable. 90% ruido, errores OCR severos.
+
+┌─────────────────────────────────────────────┐
+│ CON RED NEURONAL (SpharagusNet)             │
+├─────────────────────────────────────────────┤
+│ Valparaíso, de Septiembre de Andrés Couve  │
+│ Rioseco, Subsecretario de Educación        │
+│ Ministerio de Educación AUTORIZA...        │
+│ Que es necesario establecer procedimientos │
+│ que permitan una eficaz inserción de...    │
+└─────────────────────────────────────────────┘
+✅ Legible. 85% contenido relevante, 15% ruido residual.
+```
+
+### ¿Cómo? La red **aprende a clasificar**
+
+La red neuronal no "mejora" Tesseract. En cambio:
+
+1. **Tesseract extrae** todo texto y metadatos
+2. **Red neuronal clasifica** cada bloque: ¿es relevante o basura?
+3. **Mantiene solo lo relevante**, descarta el resto
+
+**Entrenada con 100+ documentos legislativos**, la red aprendió:
+- Qué se parece a "Artículo", "inciso", "párrafo" (patrones legislativos)
+- Qué es "Diario Oficial", "Página 5", números aislados (metadata)
+- Qué es ruido puro (caracteres aleatorios, errores OCR)
+
+### Resultado: Texto Procesable
+
+| Métrica | OCR Puro | SpharagusNet |
+|---------|----------|--------------|
+| **Contenido útil** | 10% | 85% |
+| **Ruido/Basura** | 90% | 15% |
+| **Usable para NLP** | ❌ No | ✅ Sí |
+| **Extracción de datos** | ❌ Falla | ✅ Funciona |
+| **Análisis sintáctico** | ❌ Imposible | ✅ Posible |
+| **Buscabilidad** | ❌ Pobre | ✅ Excelente |
+
+### Ventajas Prácticas
+
+✅ **Mejor ratio signal-to-noise:** La red filtra ~80% del ruido antes de que salga del pipeline
+
+✅ **Dominio específico:** Entrenada en documentos legislativos chilenos (MINVU, LeyChile), entiende la estructura y vocabulario
+
+✅ **Adaptativo:** Con más datos de entrenamiento, la red mejora automáticamente. Las heurísticas hardcodeadas requieren cambios manuales
+
+✅ **Contextual:** Entiende que "Diario" en "Diario de Implementación" es relevante, pero "Diario Oficial" en header es basura
+
+✅ **Métricas medibles:** Accuracy, Precision, Recall, F1 por epoch. Sabes exactamente qué tan bien está funcionando
+
+## Instalación
+
+### 1. Dependencia de sistema: Tesseract OCR
+
+`pytesseract` es solo un wrapper Python — el binario `tesseract` debe estar instalado en el sistema operativo:
+
+**Ubuntu / Debian / WSL:**
+```bash
+sudo apt install tesseract-ocr tesseract-ocr-spa
+```
+
+**macOS:**
+```bash
+brew install tesseract tesseract-lang
+```
+
+**Windows (nativo):**
+Descarga el instalador desde [UB-Mannheim/tesseract](https://github.com/UB-Mannheim/tesseract/wiki) y asegúrate de marcar el idioma **Spanish** durante la instalación.
+
+Verifica que quedó bien instalado:
+```bash
+tesseract --version
+tesseract --list-langs   # debe aparecer "spa"
+```
+
+### 2. Instalar el paquete
+
+```bash
+pip install spharagusnet
+```
+
+Primera vez — descargar el modelo pre-entrenado (~300 MB):
+
+```bash
+spharagusnet download
+```
+
+Para desarrollo local (editable):
+
+```bash
+git clone https://github.com/jsmdev/spharagusnet.git
+cd spharagusnet
+pip install -e ".[train]"
+```
+
+## Uso
+
+### Como librería
+
+```python
+import spharagusnet
+
+# Descargar modelo (primera vez, después se cachea)
+spharagusnet.download_model()
+
+# Extraer texto
+texto = spharagusnet.extract("documento_escaneado.pdf")
+texto = spharagusnet.extract("documento.pdf", confidence=0.6)
+
+# Verificar si el modelo está disponible
+spharagusnet.model_is_available()  # True/False
+```
+
+### CLI
+
+```bash
+# Extraer texto de un PDF
+spharagusnet extract documento.pdf
+spharagusnet extract documento.pdf -o salida.txt
+spharagusnet extract documento.pdf --confidence 0.6
+
+# Descargar/actualizar modelo
+spharagusnet download
+spharagusnet download --force
+
+# Info del paquete
+spharagusnet info
+```
+
+### Buscar documentos en BCN vía SPARQL
+
+```bash
+# Solo comunas de comunas_interes.txt
+python scripts/bcn_sparql_planes.py
+
+# Todas las comunas del CSV
+python scripts/bcn_sparql_planes.py --todas
+```
+
+> **Nota:** El script solo incluye registros cuya columna `urls_documentos` contenga un link de `instrumentosdeplanificacion.minvu.cl`. Registros sin URL de MINVU (en desarrollo, históricos sin digitalizar, o alojados en sitios municipales) se omiten del CSV de salida.
+
+### Preparar dataset y entrenar modelo
+
+```bash
+# 1. Preparar dataset (descarga PDFs, genera imágenes, cachea OCR y etiqueta bloques)
+python scripts/preparar_dataset_entrenamiento.py [--max-pares N]
+
+# 2. Entrenar modelo (con métricas en consola)
+python scripts/entrenar_modelo_extraccion.py
+
+# 3. Extraer texto de un PDF escaneado (con modelo entrenado)
+python scripts/extraer_texto_con_modelo.py <ruta_pdf> [salida.txt] [--confidence 0.5]
+```
+
+### Mejorar el modelo iterativamente
+
+```bash
+# 1. Incrementar datos gradualmente (50 → 100 → 200 → todos)
+python scripts/preparar_dataset_entrenamiento.py --max-pares 80
+
+# 2. Entrenar sobre lo existente
+python scripts/entrenar_modelo_extraccion.py --resume
+
+# 3. Si el val-F1 mejora, genial. Si estanca:
+#    - Agregar más datos (paso 1 con más pares)
+#    - Regenerar labels: borrar los .labels.json y correr paso 1 de nuevo
+#    - Ajustar patience/epochs
+
+# 4. Probar en un documento nuevo
+python scripts/extraer_texto_con_modelo.py nuevo.pdf salida.txt
+```
+
+#### `preparar_dataset_entrenamiento.py`
+- `--max-pares N` limita la cantidad de filas a procesar (por defecto todas).
+- **Incremental:** solo descarga/procesa pares nuevos; los ya existentes se saltan.
+- **Cache OCR:** guarda bloques Tesseract como `.ocr.json` junto a cada imagen, así el entrenamiento posterior no re-corre OCR.
+- **Etiquetado mejorado:** usa trigramas + similitud Levenshtein para decidir relevancia (en vez de overlap de palabras sueltas que matchea "de", "la", etc.).
+- Convierte PDFs página por página a 200 DPI para evitar consumo de RAM excesivo en WSL.
+- Exige par completo (PDF LeyChile + PDF MINVU + imágenes generadas); archivos huérfanos se eliminan automáticamente.
+
+#### `entrenar_modelo_extraccion.py`
+- `--resume`: carga el último checkpoint y continúa entrenando (no parte de cero). Expande el vocabulario automáticamente si hay palabras nuevas.
+- `--epochs N`: número de epochs (default: 20).
+- `--patience N`: early stopping patience (default: 5).
+- **Carga desde cache:** lee `.labels.json` generados por `preparar_dataset_entrenamiento.py` en vez de re-correr OCR.
+- **Métricas por epoch:** `Loss`, `Accuracy`, `Precision`, `Recall`, `F1` en train y validación.
+- Guarda:
+  - `modelo_entrenado.pth` (mejor modelo por F1)
+  - `vocab.json` (vocabulario para tokenización)
+  - `historial_entrenamiento.json` (métricas para análisis)
+
+**Arquitectura:**
+- Embedding layer (vocab → 512-D vectors)
+- Block classifier (2 capas FC con ReLU + dropout) → clasificación binaria {irrelevante, relevante}
+- LSTM (generador de texto, para futuras extensiones)
+- **Class weights** para compensar desbalance (más bloques irrelevantes que relevantes)
+
+#### `extraer_texto_con_modelo.py`
+**Flujo de inferencia:**
+1. PDF escaneado → OCR (Tesseract) extrae bloques de texto
+2. Cada bloque → Tokenización + Embedding + Red neuronal
+3. Red predice: 0 (irrelevante) ó 1 (relevante)
+4. Reconstruye documento solo con bloques relevantes
+
+**Parámetros:**
+- `--confidence THRESHOLD`: Umbral de confianza [0-1]
+  - Default: 0.5 (balance entre precision/recall)
+  - Menor threshold → más bloques (recall ↑, pero más falsos positivos)
+  - Mayor threshold → menos bloques (precision ↑, pero pierdes contenido)
+
+**Fallback:** Si el modelo no está disponible, usa heurísticas (filtros manuales)
+
+### Visualizar pipeline completo
+
+```bash
+python scripts/pipeline_completo.py
+```
+
+Muestra documentación completa del flujo, arquitectura y ejemplos de ejecución.
+
+## Arquitectura de la Red Neuronal
+
+### Diagrama del Flujo de Inferencia
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    PDF MINVU (escaneado)                 │
+└────────────────────────┬─────────────────────────────────┘
+                         │
+        ┌────────────────▼────────────────┐
+        │ 1. CONVERSIÓN PDF → IMÁGENES    │
+        │    (page-by-page, 200 DPI)      │
+        └────────────────┬─────────────────┘
+                         │
+        ┌────────────────▼────────────────────────────────┐
+        │ Para cada página:                               │
+        │                                                 │
+        │  ┌─ 2. OCR (Tesseract)                         │
+        │  │    Imagen → bloques de texto + coordenadas  │
+        │  │    (filtro: confianza > 30%)                │
+        │  │                                              │
+        │  │    [                                         │
+        │  │      {"texto": "Artículo 1", ...},          │
+        │  │      {"texto": "Página 1", ...},            │
+        │  │      {...}                                  │
+        │  │    ]                                        │
+        │  │                                              │
+        │  └─ 3. CLASIFICACIÓN (MODELO NEURONAL)         │
+        │     Para cada bloque:                          │
+        │     a) Tokenizar → [idx_1, idx_2, ...]        │
+        │     b) Embedding → 512-D vectors               │
+        │     c) Pooling → reducir a (512,)              │
+        │     d) Block Classifier (2 FC layers)          │
+        │     e) Softmax → prob(relevante)               │
+        │                                                │
+        │     ┌─────────────────────────────┐            │
+        │     │ Clasificador Binario:       │            │
+        │     │                             │            │
+        │     │ FC(512 → 256) ─ ReLU ─      │            │
+        │     │ Dropout(0.1) ─ FC(256 → 2) │            │
+        │     │                             │            │
+        │     │ Output: [logit_neg, logit_pos]│          │
+        │     │ Pred: argmax() → {0, 1}     │            │
+        │     └─────────────────────────────┘            │
+        │                                                │
+        │  └─ 4. FILTRADO                                │
+        │     Si pred=1 AND confidence >= threshold:    │
+        │       → MANTENER bloque                        │
+        │     Sino:                                      │
+        │       → DESCARTAR bloque                       │
+        │                                                │
+        └─────────────────┬──────────────────────────────┘
+                          │
+        ┌─────────────────▼──────────────┐
+        │ 5. RECONSTRUCCIÓN              │
+        │    Unir bloques relevantes     │
+        │    + limpieza de espacios      │
+        │    + separar por páginas       │
+        └─────────────────┬──────────────┘
+                          │
+        ┌─────────────────▼──────────────┐
+        │ 📄 TEXTO LIMPIO (formato      │
+        │    LeyChile, sin headers/pies) │
+        └───────────────────────────────┘
+```
+
+### Métricas Reportadas During Training
+
+La tabla de entrenamiento muestra:
+
+```
+    Epoch │   Loss    Acc   Prec   Rec    F1 │  vLoss  vAcc  vPrec  vRec   vF1 │     t     ETA
+     1/20 │  0.6932  0.650  0.580  0.720  0.642 │  0.6801  0.670  0.600  0.700  0.646 │  2.3s   41.4s
+     2/20 │  0.5234  0.710  0.620  0.750  0.680 │  0.5102  0.725  0.640  0.770  0.700 │  2.1s   39.2s
+     3/20 │  0.4521  0.760  0.680  0.800  0.735 │  0.4398  0.770  0.690  0.810  0.745 │  2.0s   37.0s
+```
+
+**Columnas:**
+- `Epoch`: Época actual / total
+- `Loss` / `vLoss`: Pérdida de entrenamiento / validación (menor es mejor)
+- `Acc`: Accuracy (% bloques clasificados correctamente)
+- `Prec`: Precision (% de positivos predichos que son realmente positivos)
+- `Rec`: Recall (% de positivos reales que fueron detectados)
+- `F1`: Media armónica de Precision y Recall (métrica de balance)
+- `t`: Tiempo que tardó la época
+- `ETA`: Tiempo estimado para terminar
+
+**Early Stopping:** El entrenamiento se detiene automáticamente si `val-F1` no mejora durante 5 epochs consecutivos, previniendo overfitting.
+
+## Publicar en PyPI
+
+```bash
+# 1. Subir modelo a GitHub Releases (tag v0.2.0)
+#    - modelo_entrenado.pth
+#    - vocab.json
+
+# 2. Build
+pip install build twine
+python -m build
+
+# 3. Publicar
+twine upload dist/*
+```