Skip to main content

agrag.common.data_models.chunk.Chunk

Bases: DataPoint

One retrieval-sized piece of a Document.

Attributes:

  • document_id (UUID) – The id of the persisted Document graph node this chunk belongs to (see Document.node_id_for). It stays stable across content versions of the same logical document. Per-version identity lives in Chunk.id instead.
  • index (int) – The position of the chunk within its document, from 0.
  • text (str) – The chunk text.
  • provenance (TextProvenance | PageProvenance) – The location of this chunk in its source. The shape of this value depends on which chunker made the chunk.
  • heading_path (list[str]) – The headings that contain this chunk, from outermost to innermost. Empty for a docling chunk and for a chunk with no heading above it.
  • content_kind (Literal['text', 'table_row', 'code', 'heading']) – The kind of content in this chunk. A text chunker always sets "text". A docling chunk can also be "table_row".
  • chunker (str | None) – The strategy name of the chunker that made this chunk. None for a chunk written before chunkers were recorded.
  • chunker_hash (str | None) – The fingerprint of the settings of the chunker that made this chunk. None for a chunk written before chunkers were recorded.
  • level (int) – 1 for a parent chunk, 0 for every other chunk. A parent chunk is the unit of extraction. A child chunk is the unit of search.
  • parent_id (UUID | None) – The id of the parent chunk of a child chunk. None for a parent and for a chunk that has no parent.

Functions:

  • id_for – Compute the chunk id.
  • section_label – Return the heading path as one line, or None when the path is empty.
  • to_node_record – Return this chunk as a GraphStore write record.

chunker​

chunker: str | None = None

chunker_hash​

chunker_hash: str | None = None

content_kind​

content_kind: Literal['text', 'table_row', 'code', 'heading'] = 'text'

contextual_text​

contextual_text: str

The text with its heading path above it, for embedding.

The stored text and its offsets do not change. A chunk with no heading path returns its text.

created_at​

created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))

document_id​

document_id: UUID

embedding​

embedding: list[float] | None = None

heading_path​

heading_path: list[str] = Field(default_factory=list)

id​

id: UUID | None = None

id_for​

id_for(*, document_id:UUID, version_id:UUID | None = None, provenance:TextProvenance | PageProvenance, index:int, chunker_hash:str | None = None, level:int = 0) -> UUID

Compute the chunk id.

For a text chunk, the id comes from the document id and the character span. A change in chunk size shifts the span, so it also changes the id. When supplied, version_id makes the id distinct for each version of a document.

For a docling chunk, the id comes from the document id, the chunker hash and the chunk index instead. The hash keeps a re-chunk with new settings from overwriting chunk N of the earlier settings. Docling parsing is not always the same between runs, so this id is not stable across a re-parse of the same source.

Parameters:

  • document_id (UUID) – The id of the parent Document.
  • version_id (UUID | None) – Optional id for the parent document version.
  • provenance (TextProvenance | PageProvenance) – The provenance of the chunk. Its type picks which id rule applies.
  • index (int) – The position of the chunk within its document.
  • chunker_hash (str | None) – The fingerprint of the chunker. Only a docling chunk uses it. A text chunk id ignores it.
  • level (int) – The chunk level. A parent chunk (level 1) adds a level part, so a parent and a child with the same span get different ids. The id of a level 0 chunk does not change.

Returns:

  • UUID – The chunk id.

index​

index: int = 0

level​

level: int = 0

metadata​

metadata: dict[str, Any] = Field(default_factory=dict)

parent_id​

parent_id: UUID | None = None

provenance​

provenance: TextProvenance | PageProvenance = Field(discriminator='kind')

section_label​

section_label() -> str | None

Return the heading path as one line, or None when the path is empty.

Whitespace runs in a heading become one space, and runs of three or more dashes become one dash, so a heading cannot end the text block of the extraction prompt.

text​

text: str

to_node_record​

to_node_record() -> NodeRecord

Return this chunk as a GraphStore write record.

Provenance is flattened to a plain JSON-safe dict via model_dump. GraphStore's own serialize.node_params only converts UUIDs and walks containers.

Raises:

  • ValueError – id is None.