Result models¶
The typed results every call returns. All are frozen Pydantic models —
serializable with .model_dump() / reconstructable with
.model_validate().
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 | png | jpeg | webp 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
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}.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
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)
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
Extract¶
ingestlib.operations.extract.models.ExtractResult ¶
Bases: BaseModel
Everything extract() produced from one document.
ingestlib.operations.extract.models.ExtractedItem ¶
Bases: BaseModel
One validated instance of the caller's schema, with per-field provenance.
value — an instance of the schema passed to extract() (a plain dict after an artifact round-trip until revalidated by load_extract) fields — one FieldValue per top-level schema field pages — every page this item drew from
ingestlib.operations.extract.models.FieldValue ¶
Bases: BaseModel
Provenance record for ONE top-level field of an extracted item.
confidence — the model's self-score, CAPPED by verification: a value whose citation didn't check out can't report certainty region_ids — page → parse region ids the value was read from (empty on the native no-parse path, which is page-level only) pages — 1-based pages the value came from grounded — True: the value's text was found in its cited source; False: cited but not found; None: not checkable (booleans, empty values, uncited fields)
Ingest¶
ingestlib.services.ingest.models.IngestResult ¶
Bases: BaseModel
Outcome of one document's journey through the full pipeline.
status — "ingested" fresh run "skipped" this checksum already completed the full pipeline (skip_existing was True) "moved" same checksum arrived from a new path — only the registry's source_path was re-pointed, nothing ran "replaced" a previous version held this source path; it was fully deleted (vectors + artifacts) after the new version went live — see replaced_doc_id doc_id — the document's content checksum; keys every artifact and vector replaced_doc_id — the old version's doc_id when status is "replaced" durations — per-stage wall-clock seconds (parse/classify/split/embed/ upsert, plus replace when an old version was deleted)
Retrieve¶
ingestlib.services.retrieve.models.RetrievalResult ¶
Bases: BaseModel
Ranked results for one question, ready for prompt building.
hits — document chunks (the default, sources-free retrieve) results — normalized items when retrieve(sources=[...]) fanned out over documents AND/OR databases; each carries its own source + provenance
context
property
¶
context: str
Numbered, cited context — paste-ready as LLM context. Renders the
mixed-source results when a sources= fan-out produced them, else the
document hits.
ingestlib.services.retrieve.models.Hit ¶
Bases: BaseModel
One retrieved chunk with both scoring signals.
vector_score — the store's retrieval score: cosine similarity on dense queries, an RRF rank score on fused hybrid queries rerank_score — reranker relevance (None when reranking was off)
citation
property
¶
citation: str
Human-readable source pointer, e.g. 'doc 7b6b95d79149 · p.4 · methods'.
ingestlib.sources.base.SourceResult ¶
Bases: BaseModel
One normalized result — a database row set, or a document chunk.
content — rendered rows or chunk text, ready for an LLM prompt source — the source's name (its key in sources.yaml) source_type — "structured" (a database) | "documents" (the corpus) provenance — how to trace it: {sql, params, verified} for SQL, {doc_id, pages, region_ids} for documents score — relevance for ranked document hits; None for exact SQL rows raw — the underlying rows or chunk objects, if the caller wants them
Lifecycle¶
ingestlib.services.lifecycle.models.RemoveResult ¶
Bases: BaseModel
Outcome of remove() — one document erased from both stores.
vectors_deleted — vectors removed from the vector store (0 when the document was parsed but never ingested) artifacts_deleted — objects removed from the artifact store
ingestlib.services.lifecycle.models.SyncResult ¶
Bases: BaseModel
Outcome of sync() — the folder and the corpus reconciled.
dry_run=True means actions is the PLAN: nothing was executed.
ingestlib.services.lifecycle.models.SyncAction ¶
Bases: BaseModel
One decision sync() made (or, under dry_run, would make) for one path or document.
action — ingest | replace | move | skip | prune | repair | error detail — extra context: the replaced doc_id, the error message, ...
ingestlib.services.lifecycle.models.BackfillResult ¶
Bases: BaseModel
Outcome of backfill() — a vector store rebuilt from stored artifacts.
skipped — doc_ids that had no split artifact (parsed but never split; they need a real ingest, not a backfill)
OCR primitives¶
ingestlib.foundations.ocr.models.Region
dataclass
¶
One layout-detected region on a page.
region_id — reading-order index on the page (0-based). Stable identifier for linking markdown/JSON output back to this region (hover-highlight UI). text — plain OCR output, always populated for text-bearing regions. content — structured output whose format depends on region_type: table → HTML chart → HTML data table formula → LaTeX text/title/caption/header/footer/reference → markdown (== text) seal → recognized text figure → empty (crop via bbox for downstream vision)
ingestlib.foundations.ocr.models.BoundingBox
dataclass
¶
Axis-aligned box in pixel coordinates. Origin is top-left of the page image.
as_tuple ¶
as_tuple() -> tuple[float, float, float, float]
(x1, y1, x2, y2) — the shape most image libraries expect.
normalized ¶
normalized(
page_width: int, page_height: int
) -> tuple[float, float, float, float]
(x1, y1, x2, y2) scaled to 0–1 relative to the page — resolution-independent.
The shape UI overlays expect: multiply by the on-screen page size to place a highlight regardless of the DPI the page was rendered at.
to_pdf_points ¶
to_pdf_points(dpi: int) -> BoundingBox
This box converted from rendered-image pixels to PDF points (72/inch).
crop ¶
crop(image_bytes: bytes) -> bytes
Return a PNG-encoded crop of image_bytes bounded by this box.
Used to extract figure/chart images and to hand region patches to the LLM.