SourceSpan is the atomic unit of evidence in CL SDK. Every extracted field, cited answer, and PCE change request traces back to one or more spans. Building spans correctly — stable IDs, accurate page ranges, meaningful section metadata — is the single most important step in producing trustworthy outputs from any CL SDK workflow.
SourceSpan Schema
The
hash field is computed automatically by CL SDK builders from the span’s text content. You do not need to set it manually. Span IDs should be derived from documentId + pageNumber + sectionId + hash so that identical text on the same page always produces the same ID.Builder Functions
CL SDK provides four builder functions that handle ID generation, hashing, and metadata normalization for you.Building Page Spans
Page spans are the best default for PDF documents. Each span covers one full page of extracted text, giving the LLM a predictable context window and making page citations exact.Building Section Spans
Section spans split page text at insurance heading boundaries. Use them when your PDF parser produces reliable headings and you want finer-grained retrieval without the overhead of chunking.PageInput[]
required
Array of page objects with
documentId, pageNumber, text, and optional sourceKind.number
default:"120"
Minimum character length for a section span. Sections shorter than this threshold are merged into the preceding span.
Building Text Spans
UsebuildTextSourceSpans for long free-text sources that don’t have natural page breaks — emails, manual notes, attachments, and HTML extracts. The builder chunks the text into overlapping windows.
string
required
Stable identifier for the source document.
string
One of
"email", "attachment", "manual_note", "html", or "plain_text".number
default:"4000"
Maximum characters per span window.
number
default:"250"
Character overlap between adjacent spans to avoid cutting evidence across boundaries.
Chunking for Retrieval
After building spans, chunk them into retrieval windows for vector search. Chunks are larger than spans and respect span boundaries, so a single chunk never splits a table row or section heading mid-sentence.SourceStore. The query agent and PCE agent use both: chunks for initial retrieval, spans for final citation.
Table Span Hierarchy
When you process documents with Docling, table content is represented as a three-level span hierarchy:1
Table span (sourceUnit: 'table')
Contains the full markdown rendering of the table. Used when the LLM needs the complete table structure for context.
2
Row span (sourceUnit: 'table_row')
One header-aware row rendered as a readable key-value string. This is the canonical evidence span for table-derived policy facts.
3
Cell span (sourceUnit: 'table_cell')
A single cell value with
columnName and rowIndex metadata. Points back to its parent row span via parentSpanId. Available for UI highlighting and precise bounding-box rendering.Span Metadata
Use themetadata field to attach arbitrary key-value pairs without polluting the core schema. Common uses:
SourceStore implementations and available as filters in SourceRetrievalQuery.