Reference for the public Python surface. Generated from docstrings with mkdocstrings.
Package¶
parsecraft
¶
parsecraft package.
Modules:
-
__about__–Version information for ParseCraft.
-
__main__–Entry point for ParseCraft CLI.
-
adapters–Adapters: parse external inputs (Markdown, HTML, ...) into the canonical IR.
-
assets–Model-asset manager: pinned downloads, cache, license records.
-
backends–Backend protocol + registry — the extension surface of ParseCraft.
-
benchmark–Reproducible backend benchmarks over local documents (Phase 2 harness).
-
cache–Content-addressed conversion cache (keyed
DocumentResultstorage). -
cli–CLI module for ParseCraft.
-
config–Generic, self-contained configuration engine (Route A).
-
environment–Detected host environment — the bridge into
parsecraft.routingplanning. -
ir–Canonical IR: typed structured chunks + deterministic Markdown projection.
-
pipeline–Auto-mode executor: analysis entry points and plan → pages dispatch.
-
providers–Provider plug-ins for the optional routing seams.
-
routing–Auto-mode routing: deterministic signal→intent planning with a judge seam.
IR — models and projection¶
ir
¶
Canonical IR: typed structured chunks + deterministic Markdown projection.
Modules:
-
markdown–Deterministic Markdown projection of the canonical IR.
-
models–Canonical intermediate representation for ParseCraft.
Classes:
-
AssetKind–Kind of an extracted asset.
-
BBox–Axis-aligned bounding box in source coordinates (points).
-
ChunkKind–Kind of a structured chunk.
-
ChunkRelation–Relation from one chunk to another chunk id.
-
CrossPageRelation–Relation between content on different pages.
-
DetectedRegion–A region detected on a page (layout signal, not yet content).
-
Diagnostic–A recorded, non-fatal observation about a page.
-
DiagnosticLevel–Severity of a diagnostic entry.
-
DocumentMetadata–Document-level metadata and reproducibility anchors.
-
DocumentResult–Root of the canonical IR — everything projections need.
-
ExtractedAsset–An asset extracted from a page (image, LaTeX source, CSV, ...).
-
FailureCode–Machine-readable cause of a structured pass failure.
-
PageRange–Inclusive 1-based page range.
-
PageResult–All extracted content of one page, in reading order.
-
PageSignal–Deterministic per-page analysis signal (planner input state).
-
PassFailure–Structured failure record — typed, never a bare string.
-
PassKind–Processing pass that produced or judged a result.
-
PassStatus–Outcome of a processing pass.
-
QualitySignal–Named quality score in [0, 1] attached to a chunk or document.
-
RegionKind–Kind of a detected page region.
-
RelationKind–Kind of chunk or cross-page relation.
-
SourceSpan–Character span in the original text source.
-
StructuredChunk–One typed content unit — the package's currency.
-
TraceEntry–One processing pass recorded in the document's trace.
Functions:
-
render_block–Render one chunk and its descendants to Markdown, depth-first in order.
-
render_page–Render one page: marker comment, then every block in reading order.
-
to_markdown–Project a full document to deterministic Markdown (trailing newline).
-
utcnow–Timezone-aware now — single home for timestamps in IR construction.
BBox
¶
Bases: _ValueModel
Axis-aligned bounding box in source coordinates (points).
ChunkRelation
¶
Bases: _ValueModel
Relation from one chunk to another chunk id.
CrossPageRelation
¶
Bases: BaseModel
Relation between content on different pages.
DetectedRegion
¶
Bases: BaseModel
A region detected on a page (layout signal, not yet content).
Diagnostic
¶
Bases: BaseModel
A recorded, non-fatal observation about a page.
DocumentMetadata
¶
Bases: BaseModel
Document-level metadata and reproducibility anchors.
DocumentResult
¶
Bases: BaseModel
Root of the canonical IR — everything projections need.
ExtractedAsset
¶
Bases: BaseModel
An asset extracted from a page (image, LaTeX source, CSV, ...).
PageRange
¶
Bases: _ValueModel
Inclusive 1-based page range.
PageResult
¶
Bases: BaseModel
All extracted content of one page, in reading order.
-
Reference
irrender_page
PageSignal
¶
Bases: BaseModel
Deterministic per-page analysis signal (planner input state).
PassFailure
¶
Bases: _ValueModel
Structured failure record — typed, never a bare string.
QualitySignal
¶
Bases: _ValueModel
Named quality score in [0, 1] attached to a chunk or document.
SourceSpan
¶
Bases: _ValueModel
Character span in the original text source.
StructuredChunk
¶
Bases: BaseModel
One typed content unit — the package's currency.
kind decides how :func:parsecraft.ir.markdown.to_markdown renders
content; metadata carries kind-specific hints (e.g.
heading_level, language) as stringly-typed JSON-safe values.
-
Reference
irrender_block
TraceEntry
¶
Bases: BaseModel
One processing pass recorded in the document's trace.
render_block
¶
render_block(chunk: StructuredChunk) -> str
Render one chunk and its descendants to Markdown, depth-first in order.
Source code in src/parsecraft/ir/markdown.py
80 81 82 83 | |
render_page
¶
render_page(page: PageResult) -> str
Render one page: marker comment, then every block in reading order.
Source code in src/parsecraft/ir/markdown.py
73 74 75 76 77 | |
to_markdown
¶
to_markdown(result: DocumentResult) -> str
Project a full document to deterministic Markdown (trailing newline).
Source code in src/parsecraft/ir/markdown.py
66 67 68 69 70 | |
Backends — protocol and registry¶
backends
¶
Backend protocol + registry — the extension surface of ParseCraft.
Modules:
-
docling–Docling backend family — MIT layout-aware parsing (CPU, heavy extra).
-
errors–Backend subsystem exceptions.
-
liteparse–LiteParse backend family — Apache-2.0 document parsing, CPU-only.
-
marker–Marker backend family — high-accuracy PDF→Markdown (Apache-2.0 / OpenRAIL-M).
-
mineru–MinerU backend family — layout-aware PDF parsing behind the
mineruextra. -
native–Built-in native backends: dependency-light document parsers.
-
ocr–OCR / document-VLM backend family — light entry points, heavy impls.
-
office_pages–Truthful page counts for OOXML office sources — stdlib-only.
-
openpyxl–The openpyxl backend package (XLSX → typed TABLE chunks).
-
options–Backend option values: one coercion, shared by the CLI and the adapters.
-
pandoc–Pandoc backend family — office/ODF/EPUB/RTF conversion (ADR-0005).
-
pdf_inspector–pdf-inspector backend family — MIT Rust/PyO3 PDF extraction, CPU-only.
-
protocol–Public backend protocol: what a backend is and what a request carries.
-
pymupdf–PyMuPDF backend — pypdf inspection, PyMuPDF extraction (ADR-0003, ADR-0009).
-
registry–Backend registry: explicit registration first, lazy entry-point discovery.
-
source–Shared
file://URI resolution for source documents. -
trafilatura–trafilatura backend — HTML → typed Markdown chunks (see AGENTS.md).
Classes:
-
AnalysisResult–Output of
DocumentBackend.analyze— planner input state. -
BackendAlreadyRegisteredError–Raised when explicit registration collides with an existing name.
-
BackendCapabilities–Static, import-free facts about a backend.
-
BackendConfig–Per-instance backend configuration passed to the factory.
-
BackendDescriptor–What the registry hands out: identity + capabilities, no code.
-
BackendError–Base class for all backend subsystem errors.
-
BackendFactory–What registration accepts: a light module-level object.
-
BackendLoadError–Recorded failure to load an entry-point backend (stored, not raised).
-
BackendNotFoundError–Raised when a backend name is not registered.
-
BackendRef–Identity of the backend that produced a result (provenance anchor).
-
BackendRegistry–Name → (descriptor, factory) binding with lazy plugin discovery.
-
BackendResult–Converged IR output of
DocumentBackend.convert. -
ConversionRequest–Everything a backend may do — bounds live here, not in global state.
-
DependencyUnavailableError–A backend's optional implementation module is not installed.
-
DocumentBackend–A backend: analyzes a source and converts bounded slices of it.
-
ModelAssetDescriptor–Pinned model-asset metadata (license + reproducibility contract).
-
PageSignal–Deterministic per-page analysis signal (planner input state).
-
SourceDocument–A document handed to a backend: path-based or in-memory.
Functions:
-
coerce_option_value–Turn an option's text into the type it obviously means.
AnalysisResult
¶
Bases: BaseModel
Output of DocumentBackend.analyze — planner input state.
-
Reference
backendsDocumentBackendanalyze
BackendAlreadyRegisteredError
¶
BackendAlreadyRegisteredError(name: str)
Bases: BackendError
Raised when explicit registration collides with an existing name.
Source code in src/parsecraft/backends/errors.py
21 22 23 | |
BackendCapabilities
¶
Bases: BaseModel
Static, import-free facts about a backend.
BackendConfig
¶
Bases: BaseModel
Per-instance backend configuration passed to the factory.
-
Reference
backends
BackendDescriptor
¶
Bases: BaseModel
What the registry hands out: identity + capabilities, no code.
-
Reference
backendsBackendRegistry
-
Reference
backendsBackendRegistrysuffixes_for
BackendFactory
¶
Bases: Protocol
What registration accepts: a light module-level object.
descriptor must carry the registry name; __call__ is the only
place heavy imports may happen.
-
Reference
backendsBackendRegistryregister
Methods:
-
__call__–Build a backend instance for
config.
__call__
¶
__call__(config: BackendConfig) -> DocumentBackend
Build a backend instance for config.
Source code in src/parsecraft/backends/protocol.py
234 235 236 | |
BackendLoadError
¶
Bases: BackendError
Recorded failure to load an entry-point backend (stored, not raised).
Discovery never raises — one broken plugin must not brick the registry.
Instances surface via BackendRegistry.load_errors so callers can
report them explicitly.
-
Reference
backendsBackendRegistryload_errors
Source code in src/parsecraft/backends/errors.py
34 35 36 37 38 | |
BackendNotFoundError
¶
BackendNotFoundError(name: str)
Bases: BackendError
Raised when a backend name is not registered.
Source code in src/parsecraft/backends/errors.py
13 14 15 | |
BackendRef
¶
Bases: BaseModel
Identity of the backend that produced a result (provenance anchor).
BackendRegistry
¶
BackendRegistry()
Name → (descriptor, factory) binding with lazy plugin discovery.
Thread-safety: all registry state (factories, load_errors, the
discovery flag) is guarded by an internal re-entrant lock and discovery
runs single-flight. The lock is NEVER held across factory(config) —
heavy model loads run outside it, so lookups never stall behind a load.
Instances are caller-owned: no memoization, no sharing (see AGENTS.md).
Methods:
-
create–Instantiate backend
name— the first heavy-import boundary. -
fingerprint–Deterministic identity of the registered backend set — a cache key.
-
get–Descriptor for
name; raises :class:BackendNotFoundError. -
list_backends–All known descriptors, sorted by name (deterministic output).
-
register–Register
factoryundernameexplicitly (highest precedence). -
suffixes–Source suffixes some registered backend can ingest (a projection).
-
suffixes_for–The suffixes ONE descriptor can ingest — the per-backend half of :meth:
suffixes. -
supported_formats–Sorted union of every registered backend's supported formats.
Attributes:
-
load_errors(dict[str, BackendLoadError]) –Copy of recorded entry-point failures — callers must surface these.
Source code in src/parsecraft/backends/registry.py
57 58 59 60 61 | |
load_errors
property
¶
load_errors: dict[str, BackendLoadError]
Copy of recorded entry-point failures — callers must surface these.
create
¶
create(name: str, config: BackendConfig | None = None) -> DocumentBackend
Instantiate backend name — the first heavy-import boundary.
A fresh, caller-owned instance per call (no memoization): residency
and VRAM admission belong to the caller, and the registry lock is
never held across factory(config) — a multi-minute model load
never blocks concurrent lookups or registrations.
Source code in src/parsecraft/backends/registry.py
138 139 140 141 142 143 144 145 146 147 | |
fingerprint
¶
fingerprint() -> str
Deterministic identity of the registered backend set — a cache key.
Derived from each backend's name, version, and supported formats: properties of the installed backend set, never host hardware. Two registries with the same backend set yield the same fingerprint on any machine; changing any backend's identity or formats changes it.
Source code in src/parsecraft/backends/registry.py
127 128 129 130 131 132 133 134 135 136 | |
get
¶
get(name: str) -> BackendDescriptor
Descriptor for name; raises :class:BackendNotFoundError.
Source code in src/parsecraft/backends/registry.py
93 94 95 96 97 98 99 100 | |
list_backends
¶
list_backends() -> list[BackendDescriptor]
All known descriptors, sorted by name (deterministic output).
Source code in src/parsecraft/backends/registry.py
87 88 89 90 91 | |
register
¶
register(name: str, factory: BackendFactory) -> None
Register factory under name explicitly (highest precedence).
Source code in src/parsecraft/backends/registry.py
65 66 67 68 69 70 71 72 73 74 75 76 77 | |
suffixes
¶
Source suffixes some registered backend can ingest (a projection).
A pure PROJECTION of parsecraft.pipeline.MEDIA_TYPES joined with each
descriptor's declared supported_formats — the MIME table stays the
single source and this is never a second one. Hosts ask "which suffixes
can my selected backend ingest" through this instead of re-deriving the
join across two modules.
installed_only=True (the default) drops backends whose optional
extra is absent, so an uninstalled backend never advertises suffixes.
GPU/VRAM/allow-OCR eligibility stays routing.rules.is_hard_eligible's
job (it needs a probed host); a host that wants full eligibility joins
this projection with that funnel rather than duplicating it here.
Source code in src/parsecraft/backends/registry.py
107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 | |
suffixes_for
staticmethod
¶
suffixes_for(descriptor: BackendDescriptor, *, installed_only: bool = True) -> set[str]
The suffixes ONE descriptor can ingest — the per-backend half of :meth:suffixes.
Source code in src/parsecraft/backends/registry.py
149 150 151 152 153 154 155 156 | |
supported_formats
¶
Sorted union of every registered backend's supported formats.
Source code in src/parsecraft/backends/registry.py
102 103 104 105 | |
BackendResult
¶
Bases: BaseModel
Converged IR output of DocumentBackend.convert.
-
Reference
backendsDocumentBackendconvert
ConversionRequest
¶
Bases: BaseModel
Everything a backend may do — bounds live here, not in global state.
cancellation is polled for a True result; timeouts and budgets are
hard expectations a backend must honor or return a structured failure.
extra="forbid" is load-bearing, not hygiene: the executor builds this
object from **RequestOptions().model_dump() (pc-c54), so a knob that
exists on RequestOptions but not here would otherwise be silently
dropped by pydantic's default and the caller would never learn. Forbidding
extras turns that silent loss into an error at the only construction site
that can hit it.
-
Reference
backendsDocumentBackendconvert
DependencyUnavailableError
¶
Bases: BackendError
A backend's optional implementation module is not installed.
Source code in src/parsecraft/backends/errors.py
44 45 46 47 | |
DocumentBackend
¶
Bases: Protocol
A backend: analyzes a source and converts bounded slices of it.
-
Reference
backends
Methods:
-
analyze–Collect deterministic signals without converting content.
-
convert–Convert the requested slice into canonical IR pages.
analyze
¶
analyze(source: SourceDocument) -> AnalysisResult
Collect deterministic signals without converting content.
Source code in src/parsecraft/backends/protocol.py
215 216 217 | |
convert
¶
convert(request: ConversionRequest) -> BackendResult
Convert the requested slice into canonical IR pages.
Source code in src/parsecraft/backends/protocol.py
219 220 221 | |
ModelAssetDescriptor
¶
Bases: BaseModel
Pinned model-asset metadata (license + reproducibility contract).
PageSignal
¶
Bases: BaseModel
Deterministic per-page analysis signal (planner input state).
SourceDocument
¶
Bases: BaseModel
A document handed to a backend: path-based or in-memory.
-
Reference
backendsDocumentBackendanalyze
coerce_option_value
¶
Turn an option's text into the type it obviously means.
"true"/"yes"/"on" → True, "false"/"no"/"off" → False, a
numeric string → int, anything else stays the raw string (an adapter's
own validator is the judge of what a non-obvious value means, and a value it
rejects must stay recognisable in its error message). Non-string values pass
through untouched, so a library caller's real bool/int is never
second-guessed.
Source code in src/parsecraft/backends/options.py
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 | |
CLI¶
cli
¶
CLI module for ParseCraft.
Modules:
-
app–Typer CLI app for ParseCraft.
-
args–CLI arguments, options, and flags for ParseCraft.
-
benchmark–parsecraft benchmark— reproducible reports over local documents. -
commands–CLI command implementations for ParseCraft.
-
config–Configuration diagnostic surface: schema, engine builder, and rendering.
-
convert–parsecraft convert— analyze, route, execute, render the IR. -
errors–Shared CLI error type: a message plus the process exit code to use.
-
inspect–parsecraft inspect— per-page analysis signals plus a routing preview. -
judges–parsecraft judges— the built-in judge providers and how to spell their specs. -
models–parsecraft models— inspect and manage the pinned model-asset cache. -
output–CLI output encoding: our writes are UTF-8, never the platform codepage.
-
verbosity–Third-party output policy: quiet by default, everything with
--verbose.
Caption attribution¶
caption
¶
Opt-in caption attribution over an existing :class:DocumentResult.
Two public functions, deliberately separate:
- :func:
attribute_captions— one batched System One request per document that labels ambiguous TABLE/FIGURE paragraphs as captions. It appendscaption_ofrelations only: no chunk is created, deleted, reclassified, or rewritten, and no text is copied anywhere. Off means never calling it. - :func:
link_same_span_captions— deterministic structural linking for already-explicit caption pairs (a CAPTION chunk sharing its exactsource_spanwith an adjacent FIGURE/TABLE). No model, no network.
Only Jev-serving providers are supported (typesafe-ai, zen). The
local endpoint (ollama/Nimble/Tev) is a different model family with
cold-start semantics this batch path does not cover, so requesting it fails
instead of degrading silently. Model tokens stay verbatim per provider
doctrine; the base URL comes only from the standard chain; the SDK default
timeout applies (cloud endpoints only).
Privacy: :func:attribute_captions sends bounded text snippets (the target
table/figure text and the candidate paragraph, each truncated to a documented
cap, with truncation flagged in the request) to the configured Jev endpoint.
Cloud endpoints traverse the network. The request carries no credentials
beyond the endpoint's own authentication, and this module never logs or
prints secrets.
Uncalibrated by design: answer probabilities are a selection signal only —
this module applies no numeric floor and reports nothing as validated or
calibrated. A pair links only when its answer is strictly well-formed: exact
option keys, finite in-range scores summing to approximately unity, a unique
maximum, and a choice naming that maximum. Anything else abstains; a
unusable response envelope fails the run. Malformed answers never produce links.
Classes:
-
CaptionError–Internal caption-attribution error (surfaced only for programming bugs).
-
CaptionFailure–Why :func:
attribute_captionsproduced no attributions from the endpoint. -
CaptionReport–Outcome of :func:
attribute_captions— counts, never document content. -
ChoiceAnswer–Public seam: the SDK's typed choice answer (
.choicesvalues). -
SystemOneClient–Public seam: the SDK client surface this module drives.
-
SystemOneResponse–Public seam: the SDK's typed System One response.
-
SystemOneSdk–Public seam: the
typesafe_sdkmodule surface, imported at call time.
Functions:
-
attribute_captions–Attribute existing caption paragraphs to their tables/figures via Jev.
-
link_same_span_captions–Link already-explicit caption pairs sharing one exact source span.
CaptionError
¶
Bases: AdapterError
Internal caption-attribution error (surfaced only for programming bugs).
CaptionFailure
¶
Bases: StrEnum
Why :func:attribute_captions produced no attributions from the endpoint.
-
Reference
captionCaptionReport
CaptionReport
dataclass
¶
CaptionReport(attributed: int, abstained: int, failure: CaptionFailure | None = None)
Outcome of :func:attribute_captions — counts, never document content.
-
Reference
captionattribute_captions
attribute_captions
¶
attribute_captions(document: DocumentResult, *, model: str | None = None) -> CaptionReport
Attribute existing caption paragraphs to their tables/figures via Jev.
One batched System One request per document over every undecided pair;
answers are validated strictly (see :func:_strict_winner) and applied
only afterwards, so an unusable response envelope changes nothing. Each linked pair
appends one caption_of relation on the paragraph chunk — chunks keep
their kinds, text, and metadata untouched.
Returns counts plus a :class:CaptionFailure when the endpoint could not
be used; on failure the document remains unchanged. Runs after
execute/cache at the caller's discretion — the caller owns the caching
model (attribute-then-cache for stability); no cached reproducibility is
claimed.
Source code in src/parsecraft/adapters/caption/__init__.py
138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 | |
link_same_span_captions
¶
link_same_span_captions(document: DocumentResult) -> int
Link already-explicit caption pairs sharing one exact source span.
A CAPTION chunk with a non-null source_span equal to an adjacent
FIGURE/TABLE chunk's span gets that relation — separately from (and never
confused with) model-selected paragraphs. Deterministic, no endpoint.
Returns the number of relations appended.
Source code in src/parsecraft/adapters/caption/__init__.py
351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 | |