Result models

What the operations return. All are Pydantic models; parse results can be saved to and loaded from the artifact store byte-identically.

Parse

ingestlib.operations.parse.models.ParseResult

Bases: BaseModel

Full parse output — the foundation object every downstream operation consumes.

pages — list of PageResult in document order source_path — path of the file that was parsed source_format — pdf | docx | pptx was_converted — True when the source was a DOCX/PPTX routed through LibreOffice before parsing source_metadata — properties extracted from the source file (title, author, subject, etc.); keys depend on the source format source_checksum — SHA256 hex digest of the source file bytes created_at — UTC timestamp of when the parse completed parse_duration_seconds — wall-clock time the parse took

markdown property

markdown: str

Whole-document markdown — pages joined in order.

page_by_num

page_by_num(page_num: int) -> PageResult

Fetch a page by its 1-indexed page number. Raises IndexError if absent.

save_images

save_images(directory: Path | str) -> list[Path]

Write every extracted figure/chart image to directory as PNG files.

Filenames match the image references inside PageResult.markdown (page{N}region{K}{type}.png). Returns the written paths.

ingestlib.operations.parse.models.PageResult

Bases: BaseModel

One parsed page.

text — plain text of the page markdown — final markdown (tables as HTML, formulas as LaTeX, charts as data tables, figures as image references + descriptions) regions — layout regions in reading order, with bboxes and region_ids; chart/figure content is LLM-enriched figures — extracted visual regions (chart/figure) as PNG crops with captions and descriptions native_text — original text-layer content from the source document image_bytes — full page rendered at image_dpi page_width — image width in pixels page_height — image height in pixels

has_native_text property

has_native_text: bool

True when the source document supplied its own text layer for this page.

word_count property

word_count: int

Whitespace-split word count of text.

region_by_id

region_by_id(region_id: int) -> Region

Fetch a region by its region_id. Raises IndexError if absent.

ingestlib.operations.parse.models.FigureImage

Bases: BaseModel

One visual region extracted from a page as an image.

region_id — reading-order index of the source region on its page region_type — "figure" | "chart" image_bytes — PNG crop of exactly this region from the rendered page caption — nearest caption region's text, "" when none was found description — the LLM's interpretation: a data table for charts, a structured description for figures/diagrams

filename

filename(page_num: int) -> str

Canonical export name — matches the references in PageResult.markdown.

Classify

ingestlib.operations.classify.models.ClassifyResult

Bases: BaseModel

Document classification verdict.

category — snake_case label; one of the caller's categories (or "uncategorized") when categories were supplied, otherwise an open-ended label the model generated from the content confidence — the model's 0-1 confidence in the verdict reasoning — one-to-two sentence justification alternatives — ranked runner-up categories; empty in open-ended mode pages_used — how many pages were actually read (caps at 100)

ingestlib.operations.classify.models.CategoryScore

Bases: BaseModel

One runner-up category with its relevance score (populated only when the caller supplied a categories dict).

Split

ingestlib.operations.split.models.SplitResult

Bases: BaseModel

Full split output — sections in document order, each with its chunks.

vocabulary — the section categories used: Pass 1's discoveries, or the caller's own (plus other when unmatched pages produced one) pages_used — pages actually read (caps at 500; skip mode may keep fewer)

chunks property

chunks: list[Chunk]

Every chunk in document order — the list the embedding phase iterates.

section_by_name

section_by_name(name: str) -> Section

First section with this name. Raises KeyError if absent.

ingestlib.operations.split.models.Section

Bases: BaseModel

Consecutive pages sharing one category, containing its natural chunks.

ingestlib.operations.split.models.Chunk

Bases: BaseModel

One natural retrieval unit — the thing the embedding phase embeds.

chunk_id — document-wide index in reading order section — name of the section this chunk belongs to heading — topic label for this chunk (from the boundary pass) text — plain-text content markdown — markdown content (tables as HTML, figures as references) embedding_text — markdown prefixed with its context breadcrumb "[category › section › heading]" — embed THIS field pages — 1-indexed page numbers this chunk spans region_ids — {page_num: [region_id, ...]} provenance back to parse regions (empty when split ran standalone without a parse) kind — dominant content type: text | table | figure | mixed token_estimate — rough size (chars/4) for embedding-batch planning

ingestlib.operations.split.models.VocabEntry

Bases: BaseModel

One section category — Pass 1's discovery or the caller's own.