Derogada: documentación técnica

Instalación y configuración

# desde PyPI
$ pip install derogada

# desarrollo
$ python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"

# demo web opcional con IA + EUR-Lex (landing + API local en :8000)
# la landing ya incluye una demo 100% navegador: BOE directo (CORS) y EUR-Lex vía proxy CORS
$ .venv/bin/pip install -e ".[demo]" && .venv/bin/python demo/server.py

La extracción funciona en dos canales: regex determinista (siempre activo, sin configuración) y LLM vía LiteLLM (opcional, mejora el recall con siglas y nombres comunes). Sin LLM configurado, todo sigue funcionando en modo solo-regex.

Variable	Para qué	Ejemplo
DEROGADA_MODEL	Modelo LiteLLM para extracción y sugerencias	gpt-5.6 · anthropic/claude-sonnet-5 · gemini/gemini-3.5-flash · openai/qwen3.6 · ollama/llama4
DEROGADA_API_BASE	Endpoint OpenAI-compatible	https://api.nan.builders/v1
DEROGADA_API_KEY	Clave del proveedor	sk-…
DEROGADA_CACHE_DIR	Directorio de la caché SQLite (defecto ~/.cache/derogada)	/tmp/derogada-cache

Uso

$ derogada check demanda.pdf                  # informe Markdown por stdout
$ derogada check demanda.docx -f json -o informe.json
$ derogada check demanda.pdf -f tabla         # tabla en terminal
$ derogada check demanda.pdf --no-llm         # solo regex
$ derogada check demanda.pdf --model openai/qwen3.6
$ derogada norma BOE-A-1992-26318             # estado de una norma suelta
$ derogada norma 32016R0679                   # también CELEX (EUR-Lex)
$ derogada cache clear                        # vacía la caché local

Como biblioteca:

from derogada import analizar_documento

informe = analizar_documento("demanda.pdf")
for r in informe.resultados:
    print(r.cita.texto, "->", r.estado.value, r.derogada_por)

Arquitectura: el pipeline

Ingesta

ingest/loader.pytxt / md / docx / pdf → texto plano. Detecta PDF escaneado sin capa de texto.

→

Extracción

extract/Doble canal: regex determinista + LLM (JSON Schema). Gazetteer de siglas. Deduplicación por norma.

→

Resolución

resolve/resolver.pyCita → identificador oficial (BOE-A… / CELEX). Valida contra metadatos. Si duda: candidatos.

→

Verificación

check/status.pyEstado de la norma Y del artículo citado contra BOE / CELLAR.

→

Sugerencia

suggest/rewrite.pyPropuesta textual solo con normas reales devueltas por la API. Sin fuente, no hay sugerencia.

→

Informe

report/Markdown, JSON o tabla. Aviso legal permanente y enlace oficial por cita.

Fuentes oficiales

Solo APIs oficiales; sin scrapers HTML. Las respuestas se cachean en SQLite (TTL 7 días) con reintentos exponenciales, para ser educados con los servicios públicos.

API de datos abiertos del BOE: https://www.boe.es/datosabiertos/api

Endpoint	Uso en Derogada
GET /legislacion-consolidada	Búsqueda de candidatos por título (DSL tipo Elasticsearch en el parámetro query, JSON)
GET …/id/{id}/metadatos	estatus_derogacion, vigencia_agotada, fecha_derogacion, numero_oficial, rango, URLs consolidada y ELI
GET …/id/{id}/analisis	Referencias posteriores: quién la deroga (SE DEROGA) o modifica (SE MODIFICA), con id_norma
GET …/id/{id}/texto/indice	Bloques del texto consolidado (artículos, disposiciones)
GET …/id/{id}/texto/bloque/{bloque}	Versiones de un artículo concreto (nivel artículo)

CELLAR / EUR-Lex: endpoint SPARQL público https://publications.europa.eu/webapi/rdf/sparql

Predicado CDM	Uso en Derogada
cdm:resource_legal_id_celex	Localiza el acto por CELEX limpio (32016R0679). El endpoint no casa literales simples con xsd:string: se filtra con FILTER(STR(?o) = "…")
cdm:resource_legal_in-force	Vigencia codificada "1"/"0"
cdm:resource_legal_date_entry-into-force cdm:resource_legal_date_end-of-validity	Entrada en vigor y fin de validez
cdm:resource_legal_repeals_resource_legal	En sentido inverso: qué acto deroga al consultado (p. ej. 95/46/CE ← RGPD)

La IA en Derogada

La IA se usa para dos cosas puntuales, y nunca para decidir si una norma está vigente: eso pertenece exclusivamente a las APIs oficiales. Un modelo generativo tiene fecha de corte y no puede saber qué está derogado hoy; el BOE y CELLAR sí.

Uso	Para qué	Cómo
extract/llm.py	Recall de citas: siglas y menciones informales ("la LRJCA", "el Estatuto de los Trabajadores") que el regex no ve	Salida estructurada con JSON Schema estricto (texto, jurisdiccion, rango, numero, articulo, alias), temperatura 0, troceo con solape en documentos largos, degradación a json_object si el proveedor no soporta json_schema
suggest/rewrite.py	Redacta la propuesta de sustitución de citas derogadas o agotadas	El prompt solo contiene datos reales devueltos por la API (norma que deroga, URL, nota oficial, contexto). Regla de oro: sin fuente oficial, no hay sugerencia; si la llamada falla, se omite en silencio

La IA lee, las fuentes deciden
El LLM propone citas; el estado (vigente, derogada, modificada) lo determinan siempre BOE y CELLAR en vivo, nunca la memoria del modelo.
El gazetteer manda sobre la memoria
Si el modelo "recuerda" una versión histórica (p. ej. ET = Ley 8/1980), el gazetteer la corrige con la remisión vigente (RDL 2/2015).
El regex prioriza
Al fusionar los dos canales, una cita del LLM que duplica una regex se descarta; el LLM solo aporta citas genuinamente nuevas. Todo se deduplica por norma.
Opcional y agnóstica
Se configura con DEROGADA_MODEL (cualquier modelo LiteLLM) + DEROGADA_API_BASE / DEROGADA_API_KEY. Sin modelo, Derogada funciona completa en modo solo-regex.

Estados y reglas de negocio

Estado	Significado
VIGENTE	La norma está en vigor y sin modificaciones posteriores consolidadas
MODIFICADA	Sigue viva pero tiene modificaciones consolidadas posteriores (con lista y fuentes)
DEROGADA	Derogada: quién la derogó y cuándo, con enlace oficial
VIGENCIA AGOTADA	Su vigencia temporal se agotó según el BOE
NO RESUELTA	Candidatos ambiguos: se listan, nunca se adivina
NO ENCONTRADA	No se pudo identificar en las fuentes oficiales

Nunca inventar
Si la desambiguación no es unívoca, la cita queda NO RESUELTA con sus candidatos. Cero alucinación de identificadores.
Doble canal de extracción
El LLM propone citas estructuradas (JSON Schema estricto); el regex valida y capta lo que falte. El gazetteer de siglas manda sobre la memoria del modelo (p. ej. ET = RDL 2/2015 vigente, no la Ley 8/1980 histórica).
Verificación a dos niveles
La norma completa (metadatos + análisis jurídico) y el artículo citado (bloque del texto consolidado): un artículo puede estar derogado aunque la norma siga viva.
Todo identificador se valida
Incluso los del gazetteer: numero_oficial y rango de la API deben casar con la cita antes de fiarse.
Sugerencias ancladas
La propuesta de cambio solo usa normas reales devueltas por la fuente oficial. Sin fuente, no hay sugerencia.

Testing, CI y publicación

Tests offline deterministas
51 tests con cassettes VCR grabadas del BOE y CELLAR reales (pytest -q en ~0.3 s sin red). El test e2e con LLM se salta si no hay clave configurada.
Lint y tipos
ruff check src tests en CI, matriz Python 3.10–3.13.
Release
Tag v* → build → tests → publicación en PyPI con Trusted Publishing (OIDC), sin tokens en el repo.

Limitaciones conocidas del MVP: sin OCR (los PDF escaneados se detectan y avisan), normativa no consolidada en el BOE queda NO ENCONTRADA, la jurisprudencia está fuera de alcance, y los textos consolidados del BOE son meramente informativos (el informe enlaza siempre la publicación oficial).