How Nammu reads a 300-page expediente: smart document segmentation

A Costa Rican expediente export is rarely one document. It is a chronological compilation: a demanda, the court's admission resolution, a dozen notification acts, a contestación, evidence exhibits, more resoluciones — all concatenated into a single PDF with no bookmarks and no metadata boundaries. Smart Document Segmentation is the pass that turns that wall of pages into a navigable, typed index the moment OCR finishes, without waiting for a human to scroll through it first.

That typed index — document_index.json — is also the foundation everything else reads from. Jurisdiction detection, Trayectorias timelines, and case-level AI analysis all consume the doc_kind labels this module produces. Getting segmentation wrong propagates errors through every downstream feature.

Two phases: cheap rules first, LLM only when genuinely needed

The module mirrors the same design philosophy as the jurisdiction classifier: a fast, free, rule-based pass runs first; a paid LLM call only ever refines what the rules genuinely could not resolve. Most pages are unambiguous — a page that opens with “SENTENCIA N° 015-2025” does not need an LLM to tell you it is a sentencia. The LLM is reserved for the hard 5–10%: vision-described scans and generic fallbacks where the extra reasoning actually earns its cost.

The core algorithm

segment_document() is the Phase-1 engine. For each page, five steps run in order:

The authorship-register guard

Before any anchor fires, _detect_authorship() reads grammatical and institutional voice cues — not document-type names — to classify a page's author as tribunal, parte, mp, or unknown:

• Tribunal register: opens with a court name, or contains ordering language ("se resuelve", "por tanto"), or matches the canonical Costa Rican judicial self-dating formula.
• Party register: opens with a salutation to the court ("señores del juzgado") or a first-person filing verb ("comparezco", "vengo a…").
• MP register: mentions "Ministerio Público" or "Fiscalía" in the first ~70 characters.

Single-phrase anchors vs. co-occurrence

Most anchors are simple: a slug maps to phrases, checked against the page head, ordered most-specific-first. But several document types cannot be reliably identified from one phrase alone, because Costa Rican procedure reuses the same generic vocabulary — “recurso de apelación”, “sentencia” — across civil, penal, familia, and notarial matters. This module has no jurisdiction parameter: segmentation runs before, and independently of, jurisdiction detection.

For these, _COOCCURRENCE_ANCHORS requires two or more independent phrase groups to all hit on the same page before pinning a type. A notarial appeal-inadmissibility filing must show both an appeal phrase and a notarial-context word (“notarial”/“notario”/“disciplinario”) before being tagged apelacion_inadmision_notarial.

A _COOCCURRENCE_NEGATION_BLOCKERS mechanism handles the one case where even two-group co-occurrence is not enough: a tribunal sentencia can narrate, deep in its reasoning, that no such incident exists in a different expediente — satisfying both phrase groups while being the opposite of a genuine filing. The fix is an explicit “unless the page also says 'no consta ningún incidente'” exclusion, scoped narrowly to the one anchor that has shown this failure mode.

One-document guards: statutes, fee letters, and continuation pages

Three situations get a document-level short-circuit before the per-page loop runs, because per-page anchor matching would misfire repeatedly across an entire attached document:

All three guards share the same shape: establish identity once from the document's opening page, then suppress the specific anchors known to misfire on that document's own body text for the rest of it.

Track-reference suppression

Some doc_kinds are explicitly about another track without themselves being a new instance of it. A defectos_querella (court flags defects in a querella) or subsanación_querella (party fixes those defects) will almost always re-quote querella-track language on the same page — but that is a reference to the existing querella, not a second querella filing.

_TRACK_ROLE encodes this as a table (references: [...] → which root track a given type points at), and _suppress_track_root_cosegments() drops any co-segment that is the root of a track already referenced by the primary segment. Extending this to a new track is one table row, not a new bespoke rule.

This suppression pass runs twice in build_document_index() — once right after the rule pass and once after the LLM pass — because a changed primary type can newly qualify or disqualify a co-segment that was not relevant before.

Filename as last-resort tie-breaker

refine_segment_types() applies filename-pattern rules — but only ever to upgrade an already-generic fallback type (escrito_generico, indeterminado, requerimiento_generico). A segment whose text anchor already resolved to querella is left alone regardless of what the filename says. This is the same “Rank-5, corroborator only” discipline documented for case-level process-type detection — the two modules independently arrived at the same rule: a filename can break a tie among weak evidence, but it can never outrank text actually read from the page.

The taxonomy — jurisdiction-agnostic by design

Every recognized doc_kind slug is grouped into one of seven authorship-shaped families. Civil, penal, laboral, familia, notarial, and tránsito slugs all coexist inside the same families — segmentation never asks “which jurisdiction is this?” That question belongs entirely to case_classifier.py, downstream.

This is a deliberate layering: segmentation identifies what kind of act a page is; jurisdiction detection later decides which branch of law the case belongs to, using the resulting doc_kind bag as one of its ranked signals (Rank 2 and 3 in the waterfall described in the jurisdiction-detection post). Keeping the two questions separate is what let the notarial/familia collision bug in §5 even be diagnosed cleanly.

The authorship map (_SLUG_AUTHORSHIP) is derived automatically from which family a slug belongs to — no hand-maintained per-slug list — which is what powers the tribunal/party guard without needing to keep two vocabularies in sync.

Phase 2: the LLM confirmation pass

llm_confirm_segments() only ever runs on segments Phase 1 flagged as confidence == "low" (vision-OCR'd boundaries) or generic (escrito_generico / resolucion_generica / indeterminado). For each candidate it sends the LLM a ~700-character snippet of the opening page, the rule layer's own guess, the independently-detected authorship register with an explicit ⚠️CONFLICTO_AUTORIA flag when register and slug disagree, and the full taxonomy grouped by family.

The prompt is explicitly fail-closed: unidentifiable party filings default to escrito_generico, tribunal acts to resolucion_generica, Fiscalía acts to requerimiento_generico. A small set of high-stakes slugs (demanda, sentencia, auto_apertura_juicio, declaratoria_herederos) require an unambiguous heading — the LLM is instructed never to assign them without one.

What the output looks like

build_document_index() writes a sidecar next to every processed PDF:

{
  "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 is only ever stamped “rules+llm” if the LLM actually reclassified at least one segment. A case that needed no LLM correction is honestly reported as “rules” — downstream consumers and auditors can always see whether the more expensive pass contributed.

Three downstream consumers read this sidecar directly: case_classifier.py (jurisdiction / process-type roll-up), classify_document_segments() (case-relevance flags layered on top), and the Trayectorias timeline builder (anchoring milestones to specific act types).

Guiding principles

The same discipline documented across jurisdiction detection and analysis gating — the specifics change, the philosophy does not.