Cómo Nammu lee un expediente de 300 páginas: segmentación inteligente de documentos

La exportación de un expediente costarricense rara vez es un solo documento. Es una compilación cronológica: una demanda, la resolución de admisión del tribunal, una docena de actos de notificación, una contestación, piezas de evidencia, más resoluciones — todo concatenado en un solo PDF sin marcadores y sin límites en los metadatos. La Segmentación Inteligente de Documentos es la pasada que convierte ese muro de páginas en un índice tipificado y navegable en el momento en que el OCR termina, sin esperar a que un humano primero lo revise.

Ese índice tipificado — document_index.json — es también la base de la que se alimenta todo lo demás. La detección de jurisdicción, las líneas de tiempo de Trayectorias y el análisis de IA a nivel de caso consumen todos las etiquetas doc_kind que produce este módulo. Segmentar mal propaga errores a través de cada funcionalidad posterior.

Dos fases: reglas económicas primero, LLM solo cuando realmente se necesita

El módulo refleja la misma filosofía de diseño que el clasificador de jurisdicción: una pasada rápida, gratuita y basada en reglas corre primero; una llamada de LLM de pago solo refina lo que las reglas realmente no pudieron resolver. La mayoría de las páginas no son ambiguas — una página que abre con “SENTENCIA N° 015-2025” no necesita un LLM para decirte que es una sentencia. El LLM se reserva para el difícil 5–10%: escaneos descritos por visión y respaldos genéricos donde el razonamiento adicional realmente vale su costo.

El algoritmo central

segment_document() es el motor de la Fase 1. Para cada página, corren cinco pasos en orden:

La salvaguarda de registro de autoría

Antes de que se dispare cualquier ancla, _detect_authorship() lee pistas de voz gramatical e institucional — no nombres de tipo de documento — para clasificar al autor de una página como tribunal, parte, mp, o unknown:

• Registro de tribunal: abre con el nombre de un tribunal, o contiene lenguaje resolutivo ("se resuelve", "por tanto"), o coincide con la fórmula canónica costarricense de autofechado judicial.
• Registro de parte: abre con un saludo al juzgado ("señores del juzgado") o un verbo de presentación en primera persona ("comparezco", "vengo a…").
• Registro de MP: menciona "Ministerio Público" o "Fiscalía" en los primeros ~70 caracteres.

Anclas de frase única vs. coocurrencia

La mayoría de las anclas son simples: un slug se mapea a frases, comparadas contra el encabezado de la página, ordenadas de más específica a más genérica. Pero varios tipos de documento no pueden identificarse de forma confiable a partir de una sola frase, porque el procedimiento costarricense reutiliza el mismo vocabulario genérico — “recurso de apelación”, “sentencia” — en asuntos civiles, penales, de familia y notariales. Este módulo no tiene parámetro de jurisdicción: la segmentación corre antes, e independientemente, de la detección de jurisdicción.

Para estos casos, _COOCCURRENCE_ANCHORS exige que dos o más grupos de frases independientes coincidan en la misma página antes de fijar un tipo. Un escrito notarial de inadmisión de apelación debe mostrar tanto una frase de apelación como una palabra de contexto notarial (“notarial”/“notario”/“disciplinario”) antes de ser etiquetado apelacion_inadmision_notarial.

Un mecanismo _COOCCURRENCE_NEGATION_BLOCKERS maneja el único caso donde ni siquiera la coocurrencia de dos grupos es suficiente: una sentencia del tribunal puede narrar, en el fondo de su razonamiento, que tal incidente no existe en un expediente distinto — satisfaciendo ambos grupos de frases mientras es lo opuesto a un escrito genuino. La solución es una exclusión explícita de “a menos que la página también diga 'no consta ningún incidente'”, aplicada estrechamente solo al ancla que ha mostrado este modo de falla.

Salvaguardas de un solo documento: estatutos, cartas de honorarios y páginas de continuación

Tres situaciones reciben un cortocircuito a nivel de documento antes de que corra el bucle por página, porque la comparación de anclas por página fallaría repetidamente en todo un documento adjunto:

Las tres salvaguardas comparten la misma forma: establecer la identidad una vez a partir de la página inicial del documento, luego suprimir las anclas específicas que se sabe fallan sobre el propio texto del cuerpo de ese documento el resto de él.

Supresión de referencias de vía

Algunos doc_kinds tratan explícitamente sobre otra vía sin ser ellos mismos una nueva instancia de esa vía. Un defectos_querella (el tribunal señala defectos en una querella) o subsanación_querella (la parte corrige esos defectos) casi siempre volverá a citar lenguaje de la vía de querella en la misma página — pero eso es una referencia a la querella existente, no una segunda querella.

_TRACK_ROLE codifica esto como una tabla (references: [...] → a qué vía raíz apunta un tipo dado), y _suppress_track_root_cosegments() descarta cualquier co-segmento que sea la raíz de una vía ya referenciada por el segmento principal. Extender esto a una nueva vía es una fila de tabla, no una regla nueva a medida.

Esta pasada de supresión corre dos veces dentro de build_document_index() — una justo después de la pasada de reglas y otra después de la pasada del LLM — porque un tipo principal modificado puede calificar o descalificar de nuevo un co-segmento que antes no era relevante.

Nombre de archivo como desempate de último recurso

refine_segment_types() aplica reglas de patrón de nombre de archivo — pero solo para mejorar un tipo de respaldo ya genérico (escrito_generico, indeterminado, requerimiento_generico). Un segmento cuyo ancla de texto ya se resolvió a querella se deja intacto sin importar lo que diga el nombre de archivo. Esta es la misma disciplina de “Rango 5, solo corrobora” documentada para la detección de tipo de proceso a nivel de caso — los dos módulos llegaron independientemente a la misma regla: un nombre de archivo puede romper un empate entre evidencia débil, pero nunca puede superar el texto realmente leído de la página.

La taxonomía — agnóstica de jurisdicción por diseño

Cada slug doc_kind reconocido se agrupa en una de siete familias moldeadas por autoría. Los slugs civiles, penales, laborales, de familia, notariales y de tránsito coexisten todos dentro de las mismas familias — la segmentación nunca pregunta “¿qué jurisdicción es esta?” Esa pregunta pertenece por completo a case_classifier.py, en una etapa posterior.

Esta es una separación deliberada por capas: la segmentación identifica qué tipo de acto es una página; la detección de jurisdicción luego decide a qué rama del derecho pertenece el caso, usando la bolsa resultante de doc_kind como una de sus señales clasificadas (Rango 2 y 3 en la cascada descrita en la publicación de detección de jurisdicción). Mantener las dos preguntas separadas es lo que permitió que el bug de colisión notarial/familia del §5 pudiera diagnosticarse limpiamente.

El mapa de autoría (_SLUG_AUTHORSHIP) se deriva automáticamente de a qué familia pertenece un slug — sin lista mantenida a mano por slug — lo cual es lo que alimenta la salvaguarda tribunal/parte sin necesidad de mantener sincronizados dos vocabularios.

Fase 2: la pasada de confirmación por LLM

llm_confirm_segments() solo corre sobre segmentos que la Fase 1 marcó como confidence == "low" (límites obtenidos por OCR de visión) o genéricos (escrito_generico / resolucion_generica / indeterminado). Para cada candidato envía al LLM un fragmento de ~700 caracteres de la página de apertura, la propia suposición de la capa de reglas, el registro de autoría detectado independientemente con una bandera explícita ⚠️CONFLICTO_AUTORIA cuando el registro y el slug no coinciden, y la taxonomía completa agrupada por familia.

El prompt es explícitamente de cierre seguro: los escritos de parte no identificables recurren a escrito_generico, los actos del tribunal a resolucion_generica, los actos de la fiscalía a requerimiento_generico. Un pequeño conjunto de slugs de alto riesgo (demanda, sentencia, auto_apertura_juicio, declaratoria_herederos) requiere un encabezado inequívoco — al LLM se le instruye no asignarlos nunca sin uno.

Cómo se ve la salida

build_document_index() escribe un sidecar junto a cada PDF procesado:

{
  "schema_version": 1,
  "file_name": "Expediente-0031-PRINCIPAL.pdf",
  "num_pages": 307,
  "proceso_type": "ordinario",
  "method": "rules+llm",
  "document_segments": [
    {
      "type": "caratula_datos_generales",
      "page_start": 0, "page_end": 0,
      "confidence": "high",
      "source": "anchor",
      "count": 1
    },
    {
      "type": "demanda",
      "page_start": 1, "page_end": 8,
      "confidence": "high",
      "source": "anchor"
    },
    {
      "type": "notificacion",
      "page_start": 9, "page_end": 51,
      "confidence": "high",
      "source": "anchor",
      "count": 24
    },
    ...
  ]
}

method solo se marca como “rules+llm” si el LLM realmente reclasificó al menos un segmento. Un caso que no necesitó ninguna corrección de LLM se reporta honestamente como “rules” — los consumidores y auditores posteriores siempre pueden ver si la pasada más costosa contribuyó.

Tres consumidores posteriores leen este sidecar directamente: case_classifier.py (consolidado de jurisdicción / tipo de proceso), classify_document_segments() (banderas de relevancia de caso superpuestas), y el constructor de línea de tiempo de Trayectorias (anclando hitos a tipos de acto específicos).

Principios rectores

La misma disciplina documentada en la detección de jurisdicción y las restricciones de análisis — los detalles cambian, la filosofía no.