Eng RAG Chunking Rules Legal Docs

RAG Chunking Rules — Legal Documents

What it does

Legal documents have a rigid hierarchical structure (Parts → Articles → Clauses → Sub-clauses) that generic text splitters destroy. Splitting a 200-word Article across two chunks means neither chunk contains the full legal proposition, guaranteeing poor retrieval. This skill defines the chunking strategy for the document ingestion pipeline so that retrieval returns complete, coherent legal units.

Setup / auth

No separate auth. The chunker runs as part of the document ingestion pipeline, after PII redaction ([[eng-pii-redaction-preprocessor]]) and before embedding/storage ([[eng-supabase-index-knowledge-pipeline]]).

Dependencies: a PDF/DOCX text extractor (e.g., pdf-parse, mammoth), a boundary-detection function, and a vector DB insert (Supabase pgvector).

Capabilities

Chunk-size targets

Use token counts (cl100k_base or equivalent), not character counts. Character counts fail badly for Arabic (higher token density).

Boundary detection rules — in priority order

1. Article / Clause heading — any line matching patterns such as Article \d+, المادة \d+, Clause \d+, Section \d+, Article \d+ (French). Always start a new chunk at a heading boundary.
2. Numbered paragraph — (\d+\.\d+) or (\d+)\. at line start within an article. Sub-clauses ≥ 100 tokens get their own chunk; shorter sub-clauses are merged into the parent clause chunk.
3. Double newline — blank line between paragraphs in a judgment. Treat as a soft boundary: merge with next paragraph if combined length < target.
4. Sentence boundary (fallback only) — split at period + capitalized word only when a chunk would otherwise exceed the hard maximum. Never split within a sentence.

Metadata to attach to every chunk

interface ChunkMetadata {
  docId: string;            // UUID of parent document
  tenantId: string;         // firm/workspace UUID
  chunkIndex: number;       // 0-based sequence within doc
  chunkType: "clause" | "article" | "recital" | "definition" | "judgment_para" | "other";
  headingText?: string;     // nearest parent heading (e.g., "Article 7 — Confidentiality")
  pageNumber?: number;      // from PDF extractor
  language: "ar" | "en" | "fr" | "mixed";
  jurisdiction?: string;    // if detectable from doc metadata
  documentType: "contract" | "legislation" | "judgment" | "regulation" | "unknown";
  charStart: number;        // character offset in original text
  charEnd: number;
}

The headingText field is the single most important retrieval aid: it tells the LLM "this chunk is from Article 7 — Confidentiality" before the user even asks.

Arabic-specific rules

• Arabic contracts number articles right-to-left in the source PDF but the text extraction linearizes them left-to-right. Detect Arabic headings with: /^(المادة|البند|الفقرة)\s+\d+/.
• Arabic legal text is denser (more information per token) than English. Use the smaller end of the target range.
• Mixed AR/EN contracts (Arabizi headers + English body): detect language per paragraph and tag language: "mixed".
• Diacritics (tashkeel) inflate token counts but add no retrieval value. Strip before embedding; keep in stored raw text.

Overlap strategy

• Use overlap only for contract clauses and judgment paragraphs — not for legislative articles (which are self-contained by design).
• Overlap is a trailing tail: append the last N tokens of chunk N to the start of chunk N+1. Do not repeat the heading — duplicate headings confuse rerankers.
• Never use overlap across article/clause heading boundaries. The heading itself acts as the semantic bridge.

Usage patterns

Basic pipeline

async function ingestDocument(file: File, tenantId: string): Promise<void> {
  const rawText = await extractText(file);                          // PDF/DOCX → string
  const { redacted } = redactPII(rawText, { mode: "hash" });        // safety gate
  const chunks = chunkLegalDocument(redacted, {
    language: detectLanguage(redacted),
    documentType: classifyDocumentType(redacted),
  });
  const embeddings = await embedBatch(chunks.map(c => c.text));
  await storeChunks(chunks, embeddings, tenantId);
}

chunkLegalDocument function contract

function chunkLegalDocument(
  text: string,
  options: { language: "ar" | "en" | "fr" | "mixed"; documentType: string }
): Array<{ text: string; metadata: ChunkMetadata }>;

Retrieval hint

When retrieving, always include headingText and documentType in the returned context so the LLM can attribute the source clause in its response.

Permissions & safety

• Chunking must occur after PII redaction. Never embed PII.
• Each chunk's tenantId must be set before database insert; the RLS policy (see [[eng-tenant-isolation-row-level-security]]) enforces that only the owning tenant can retrieve it.
• Chunks of documents the user has not shared with the AI should never be returned by vector search. Apply a WHERE tenant_id = current_tenant_id() AND doc_id = ANY($sharedDocs) filter.

Failure modes

Related skills

• [[eng-pii-redaction-preprocessor]] — must run before chunking
• [[eng-supabase-index-knowledge-pipeline]] — stores the chunks and embeddings
• [[eng-tenant-isolation-row-level-security]] — RLS that scopes chunk retrieval
• [[eng-supabase-edge-functions-patterns]] — deployment pattern for the ingestion worker