En desarrollo activo • Código abierto • CC BY-NC-SA 4.0

La mejor forma de trabajar
con normativa chilena

Pipeline ELT completo para descargar, procesar y almacenar normas legales chilenas desde los servicios web de la Biblioteca del Congreso Nacional. Pensado para investigadores, desarrolladores y organizaciones.

Comenzar Ver en GitHub Documentación
Python 3.9+ PostgreSQL 15+ FastAPI Docker lxml Textual TUI spaCy NLP
git clone https://github.com/AlexFT257/BCNExtractor.git
+100
Instituciones BCN
ELT
Pipeline completo
FTS
Full-text en español
REST
API con FastAPI

Todo lo que necesitas

BCN Extractor cubre el pipeline completo: extracción, parseo XML, almacenamiento estructurado, versionado histórico y múltiples interfaces de uso.

Extracción Automatizada

Descarga normas desde los servicios web de la BCN de forma eficiente y resiliente. Incluye reintentos automáticos, rate limiting configurable, caché local para minimizar requests y detección de cambios via hash MD5 para evitar upserts innecesarios.

BCNClient XML Parser Retry logic MD5 diff

Almacenamiento Estructurado

PostgreSQL con FTS en español, índices GIN y tabla EAV de metadata (normas_metadata) con claves como materia, organismo y derogado.

Búsqueda Full-Text

Búsqueda en español sobre títulos y contenido de normas con ranking de relevancia. Búsqueda por clave de metadata (materia, organismo, derogado).

TUI Interactiva

Interfaz de terminal con Textual: navegación de normas, sync con barra de progreso, lector a pantalla completa y dashboard con estadísticas en tiempo real.

Scheduler Automático

Proceso independiente cross-platform para sincronización programada de instituciones. Configurable por hora, minuto, día de la semana y gap entre instituciones.

→ Corre en background sin bloquear
→ Estado por ejecución en scheduler_jobs
→ Compatible con Windows, Mac y Linux
→ Logs en logs/scheduler.log

Versionado Histórico Auditable

Cada vez que el sync detecta que el XML de una norma cambió (hash MD5 distinto), archiva el estado anterior en normas_versiones antes de sobreescribir. Permite auditar el contenido histórico de cualquier ley — los archivos anteriores se guardan como {id}_v{n}.xml.

normas_versiones MD5 diff XML archivado Auditable

Deploy con Docker

PostgreSQL + Python en contenedores. Credenciales del .env.example funcionan sin modificar en desarrollo local.

docker-compose up -d && pip install -r requirements.txt

REST API con FastAPI

API REST modular con Swagger UI y ReDoc integrados. Endpoints para buscar, listar, filtrar por fecha/tipo/estado y consultar normas programáticamente. Paginación en todos los endpoints, CORS configurable y health check.

GET /normas GET /normas/search GET /instituciones Swagger UI
Experimental: modo LLM

Análisis NLP de Normas

Pipeline NLP opcional que corre sobre el XML ya cacheado, sin tráfico adicional a la BCN. Extrae referencias normativas entre leyes, entidades nombradas (organismos, personas, lugares) y oraciones de obligación con su sujeto y plazo. Incluye un grafo inverso: dado cualquier decreto, muestra qué otras normas lo citan.

Referencias

Detecta y vincula citas entre normas via EntityRuler. Las no resueltas se completan de forma diferida a medida que crecen las instituciones sincronizadas.

NER + Obligaciones

Entidades nombradas con es_core_news_lg (o Ollama/gemma4 en modo LLM). Obligaciones y plazos extraídos del árbol sintáctico de dependencias.

Gestión completa

Análisis individual o en batch por institución. Borrado parcial o completo con nlp eliminar por tabla: referencias, entidades, obligaciones.

spaCy EntityRuler es_core_news_lg Ollama/gemma4 Grafo inverso NLPManager

Arquitectura del sistema

Pipeline ELT modular con capas claramente separadas y múltiples interfaces de acceso.

01

BCN Client

HTTP, caché, reintentos automáticos y rate limiting configurable.

bcn_client.py
→
02

XML Parser

lxml — extrae metadata, convierte a Markdown y detecta cambios via MD5.

utils/norm_parser.py
→
03

Managers

Normas, Metadata EAV, Instituciones, Tipos, Versiones, Schedules y NLPManager.

managers/
→
04

PostgreSQL

FTS en español, índices GIN, tabla EAV de metadata y versionado histórico.

docker-compose.yml
→
05

NLP Analyzer

Referencias, NER, obligaciones y grafo inverso — sobre el XML cacheado.

utils/nlp.py
CLI — bcn_cli.py
TUI — bcn_tui.py
REST API — api/main.py
Scheduler — scheduler_runner.py
NLP — utils/nlp.py

En marcha en minutos

Requiere Docker Desktop (o Docker Engine + Compose), Python 3.9+ y Git.

1

Clonar repositorio 

git clone https://github.com/AlexFT257/BCNExtractor.git
cd BCNExtractor
2

Configurar y levantar 

cp .env.example .env
docker-compose up -d
pip install -r requirements.txt
3

Inicializar base de datos 

# Crea tablas y carga instituciones desde CSV
python bcn_cli.py init
4

Sincronizar y explorar 

# TUI interactiva
python bcn_tui.py

# O via CLI directamente
python bcn_cli.py normas sync 17 --limit 50
fastapi dev api/main.py

Las credenciales del .env.example coinciden con el docker-compose.yml, por lo que el proyecto funciona sin editar el .env en desarrollo local. FastAPI genera documentación en localhost:8000/docs y localhost:8000/redoc.

Roadmap

El proyecto sigue un plan de fases bien definido.

Ver roadmap completo →
Completada

Fase 1 — MVP v1.0

  • ✓Extracción de instituciones
  • ✓Descarga de normas por institución
  • ✓Almacenamiento en PostgreSQL
  • ✓CLI básica + Docker setup
Completada

Fase 2 — Optimización v1.1

  • ✓Sistema de caché local
  • ✓Rate limiting configurable
  • ✓Reintentos automáticos
  • ✓FTS español + detección MD5
Completada

Fase 3 — TUI v2 y CLI v2

  • ✓TUI con Textual + progreso
  • ✓Lector de normas a pantalla completa
  • ✓CLI unificada con Typer y Rich
  • ✓Tests de CLI con CliRunner
Completada

Fase 4 — API + Datos v3

  • ✓REST API modular con FastAPI
  • ✓Scheduler cross-platform
  • ✓Metadata EAV + versionado histórico
  • ✓Tests de integración
Completada

Fase 5 — Análisis NLP

  • ✓Referencias normativas entre leyes
  • ✓NER: organismos, personas, lugares
  • ✓Obligaciones y plazos sintácticos
  • ✓Grafo inverso + modo LLM (experimental)