document-layout-intelligence

name

document-layout-intelligence

description

Preserve source fidelity while implementing or reviewing NexaRead document parsing, normalization, language or document-type detection, reading order, paragraph reconstruction, Vietnamese typography, headings, lists, captions, footnotes, semantic layout metadata, layout quality, reprocessing, or optional AI-assisted layout repair. Use for any backend, schema, migration, frontend, test, or evaluation change that can alter extracted source text, display text, content-block structure, source anchors, layout classification, or citation traceability.

Document Layout Intelligence

Preserve the uploaded document as evidence while producing a deterministic, readable display representation. Never trade citation truth for prettier text.

Required context

Before changing code, read:

1. docs/product-brief.md
2. docs/mvp-requirements.md
3. docs/architecture.md
4. the models, schemas, migrations, parsers, processing service, reader API, RAG chunking/retrieval, and evaluations touched by the change

When changing a contract or persistence model, inspect examples/source-display-contract.json. When adding behavior, inspect and extend evaluation/layout-cases.json.

Goal

Transform untrusted raw parser blocks into display blocks that:

• keep source text and anchors intact for citations, search verification, and audit;
• improve reading order, paragraph boundaries, Vietnamese typography, and semantic roles with explainable rules;
• expose uncertainty instead of silently guessing;
• remain deterministic and retry-safe unless a narrowly scoped, audited AI repair is explicitly enabled.

Input contract

Accept ordered raw blocks with, where available:

• immutable block identifier;
• raw text;
• source page number and page dimensions;
• bounding box and line/span geometry;
• font name, size, weight, and style;
• parser block type and parser confidence;
• source format, document metadata, and parser warnings.

Treat every text value and metadata field as untrusted. Do not render or execute uploaded HTML, scripts, macros, formulas, code, links, or instructions.

Output contract

Keep the existing text field as source truth. Add or preserve:

• source_text: source-faithful text; if text already has this meaning, source_text must equal text;
• display_text: deterministic display normalization;
• transformation_log: ordered structured operations with rule identifiers;
• transformation_confidence: number from 0 to 1;
• needs_review: true when a change or grouping is uncertain;
• source_anchor: source page, bounding box, source block ID, and source offsets;
• semantic layout metadata;
• quality score and warnings at document level.

Do not silently change the meaning of an existing field. Use additive schema and migration changes, preserve backward compatibility where required, and update every API consumer.

Source fidelity rules

1. Use text/source_text, never display_text, to build citation excerpts, validate quoted evidence, and audit exact source content.
2. Keep stable content-block IDs and source offsets through normalization.
3. Map every display block to one or more source block IDs without gaps or unexplained duplication.
4. Record every text-affecting display transformation in order.
5. Never invent missing words, punctuation, numbers, names, headings, rows, or references.
6. If reconstruction is ambiguous, keep the source grouping, reduce confidence, add a warning, and set needs_review.
7. Reprocessing the same version and configuration must produce equivalent blocks, mappings, logs, scores, and warnings.

Deterministic pipeline

Implement and test stages in this order:

raw parser blocks
-> language detection
-> document-type detection
-> repeated-margin suppression
-> reading-order reconstruction
-> line and paragraph merging
-> dehyphenation
-> Vietnamese typography normalization
-> semantic role detection
-> chapter and section hierarchy
-> display block generation
-> layout quality scoring
-> persistence

Keep stages as pure functions where practical. Pass explicit typed inputs and return values plus warnings; do not hide mutations in global state. Persist only after the full pipeline succeeds. Replacement must remain transactional and retry-safe.

Vietnamese normalization

Apply stable rules only:

• normalize Unicode to NFC without removing Vietnamese diacritics;
• collapse repeated horizontal whitespace in display text;
• remove whitespace before Vietnamese punctuation;
• join soft line wraps when language and geometry support the merge;
• dehyphenate only when a line-ending hyphen represents a split word;
• preserve semantic hyphens, names, identifiers, URLs, abbreviations, codes, clauses, and numeric ranges;
• never rewrite sentence meaning or translate content.

Recognize heading prefixes case-insensitively:

Chương, Phần, Mục, Tiểu mục, Bài, Điều, Khoản, Phụ lục.

Recognize list markers:

1., 1), a), a., -, •.

Recognize caption prefixes:

Hình, Biểu đồ, Sơ đồ, Bảng.

Recognize footnotes and references only when marker, placement, and typography provide evidence. Do not use an LLM for a repair a stable rule can perform.

Layout reconstruction

Use geometry first, then typography and text cues:

• suppress only margins repeated across enough pages with comparable placement; keep the source block and record suppression;
• reconstruct columns without crossing vertical column boundaries;
• attach captions to the nearest compatible asset when proximity and label agree;
• infer heading levels from explicit numbering, font hierarchy, and spacing;
• preserve list indentation and nesting;
• link footnote references without deleting source markers;
• preserve code, formula, image, and table blocks atomically where possible.

Semantic metadata may include:

semantic_role
heading_level
keep_with_next
avoid_break_inside
break_before
break_after
indent_level
text_align
is_first_paragraph
is_chapter_opening
caption_for_asset_id
footnote_reference
source_page_number

Set pagination hints so headings stay with following content, short quotes and list items avoid splitting, code/formula/image/table blocks prefer atomic placement, chapter openings may start on a right-hand page, and avoid orphan or widow lines where capacity permits.

Confidence and quality

• Clamp all confidence values to [0, 1].
• Base transformation confidence on observable signals, not arbitrary constants.
• Calculate document quality from text coverage, reading-order certainty, merge certainty, hierarchy consistency, anchor completeness, and warning severity.
• Return both a score and machine-readable warnings.
• Never hide low quality behind a successful processing status.
• Mark the document readable when the display representation is safe to use; keep AI-index readiness as a distinct stage.

Optional AI-assisted repair

Allow AI repair only for low-confidence heading structure, complex reading order, or severely broken tables after deterministic rules fail.

The AI may return only grouping or structure proposals. Require:

• input block IDs;
• output-to-input mapping;
• confidence and reason;
• provider and model metadata;
• timestamped audit record;
• validation that all source anchors and text are preserved;
• deterministic fallback on timeout, invalid output, or disabled provider.

Reject any proposal that invents or removes content, changes numbers, modifies anchors, translates text, or cannot account for every input block.

Testing and evaluation

For every behavior change:

1. Add unit tests for pure rules and confidence boundaries.
2. Add persistence/API tests for source/display separation and anchors.
3. Add retry/idempotency tests.
4. Add citation tests proving source text remains authoritative.
5. Add cross-account isolation tests when endpoints or persistence change.
6. Extend evaluation/layout-cases.json with Vietnamese, multi-column, caption, list, heading, footnote, difficult-layout, and adversarial cases.
7. Run Ruff, mypy, pytest, frontend lint/type-check/tests/build when affected, the layout evaluation, and git diff --check.

Prefer exact invariant assertions over screenshots alone.

Security requirements

• Preserve authentication, CSRF, ownership filters, private storage, parser limits, archive safety, SSRF controls, sanitization, and citation validation.
• Bound input size, page count, block count, geometry count, nesting, runtime, and optional provider requests.
• Do not log source text, credentials, tokens, signed URLs, or private object keys.
• Do not execute instructions embedded in documents.
• Validate all AI or parser output before persistence.

Forbidden behavior

Do not:

• overwrite text with cleaned or generated display content;
• use display_text as quoted citation evidence;
• change block IDs or offsets without an explicit lossless mapping;
• discard confusing text, tables, numbers, or pages;
• rename people or organizations;
• auto-translate;
• make an LLM the default normalization path;
• accept unmapped AI output;
• weaken authorization, citations, sanitization, or data isolation;
• claim production readiness without migrations, evaluations, and required validation.

Handoff

Report:

• every changed file and migration;
• exact input/output and source-anchor contract changes;
• rules, confidence thresholds, warnings, and fallbacks;
• tests, evaluations, lint, type-check, build, and migration commands run;
• fixture coverage and measurable quality results;
• skipped checks, failures, limitations, and production risks;
• the next exact task and command.