Skip to content

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 DocumentResult storage).

  • cli –

    CLI module for ParseCraft.

  • config –

    Generic, self-contained configuration engine (Route A).

  • environment –

    Detected host environment — the bridge into parsecraft.routing planning.

  • 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.

AssetKind

Bases: StrEnum

Kind of an extracted asset.

BBox

Bases: _ValueModel

Axis-aligned bounding box in source coordinates (points).

ChunkKind

Bases: StrEnum

Kind of a structured chunk.

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.

DiagnosticLevel

Bases: StrEnum

Severity of a diagnostic entry.

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, ...).

FailureCode

Bases: StrEnum

Machine-readable cause of a structured pass failure.

PageRange

Bases: _ValueModel

Inclusive 1-based page range.

PageResult

Bases: BaseModel

All extracted content of one page, in reading order.

PageSignal

Bases: BaseModel

Deterministic per-page analysis signal (planner input state).

PassFailure

Bases: _ValueModel

Structured failure record — typed, never a bare string.

PassKind

Bases: StrEnum

Processing pass that produced or judged a result.

PassStatus

Bases: StrEnum

Outcome of a processing pass.

QualitySignal

Bases: _ValueModel

Named quality score in [0, 1] attached to a chunk or document.

RegionKind

Bases: StrEnum

Kind of a detected page region.

RelationKind

Bases: StrEnum

Kind of chunk or cross-page relation.

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.

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
def render_block(chunk: StructuredChunk) -> str:
    """Render one chunk and its descendants to Markdown, depth-first in order."""
    parts = [render_chunk(chunk), *(render_block(child) for child in chunk.children)]
    return "\n\n".join(part for part in parts if part)

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
def render_page(page: PageResult) -> str:
    """Render one page: marker comment, then every block in reading order."""
    body = "\n\n".join(render_block(block) for block in page.blocks)
    marker = f"<!-- page {page.page_number} -->"
    return f"{marker}\n\n{body}" if body else marker

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
def to_markdown(result: DocumentResult) -> str:
    """Project a full document to deterministic Markdown (trailing newline)."""
    if not result.pages:
        return ""
    return "\n\n".join(render_page(page) for page in result.pages) + "\n"

utcnow

utcnow() -> datetime

Timezone-aware now — single home for timestamps in IR construction.

Source code in src/parsecraft/ir/models.py
385
386
387
def utcnow() -> datetime:
    """Timezone-aware now — single home for timestamps in IR construction."""
    return datetime.now(UTC)

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 mineru extra.

  • 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:

Functions:

AnalysisResult

Bases: BaseModel

Output of DocumentBackend.analyze — planner input state.

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
def __init__(self, name: str) -> None:
    super().__init__(f"backend already registered: {name!r}")
    self.name = name

BackendCapabilities

Bases: BaseModel

Static, import-free facts about a backend.

BackendConfig

Bases: BaseModel

Per-instance backend configuration passed to the factory.

BackendDescriptor

Bases: BaseModel

What the registry hands out: identity + capabilities, no code.

BackendError

Bases: Exception

Base class for all backend subsystem errors.

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.

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
def __call__(self, config: BackendConfig) -> DocumentBackend:
    """Build a backend instance for ``config``."""
    ...

BackendLoadError

BackendLoadError(name: str, cause: Exception | None = None)

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.

Source code in src/parsecraft/backends/errors.py
34
35
36
37
38
def __init__(self, name: str, cause: Exception | None = None) -> None:
    detail = f": {type(cause).__name__}: {cause}" if cause is not None else ""
    super().__init__(f"failed to load backend {name!r} from entry point{detail}")
    self.name = name
    self.cause = cause

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
def __init__(self, name: str) -> None:
    super().__init__(f"backend not registered: {name!r}")
    self.name = name

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 factory under name explicitly (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:

Source code in src/parsecraft/backends/registry.py
57
58
59
60
61
def __init__(self) -> None:
    self._factories: dict[str, BackendFactory] = {}
    self._load_errors: dict[str, BackendLoadError] = {}
    self._entry_points_loaded = False
    self._lock = threading.RLock()

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
def create(self, 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.
    """
    factory = self._factory_for(name)
    return factory(config if config is not None else BackendConfig(name=name))

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
def fingerprint(self) -> 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.
    """
    canonical = "\n".join(f"{d.name}@{d.version}|{','.join(sorted(d.capabilities.supported_formats))}" for d in self.list_backends())
    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()

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
def get(self, name: str) -> BackendDescriptor:
    """Descriptor for ``name``; raises :class:`BackendNotFoundError`."""
    self._load_entry_points()
    with self._lock:
        factory = self._factories.get(name)
    if factory is None:
        raise BackendNotFoundError(name)
    return factory.descriptor

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
def list_backends(self) -> list[BackendDescriptor]:
    """All known descriptors, sorted by name (deterministic output)."""
    self._load_entry_points()
    with self._lock:  # snapshot: concurrent register() cannot resize mid-iteration
        return [factory.descriptor for name, factory in sorted(self._factories.items())]

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
def register(self, name: str, factory: BackendFactory) -> None:
    """Register ``factory`` under ``name`` explicitly (highest precedence)."""
    if not isinstance(factory, BackendFactory):
        msg = f"factory for {name!r} does not implement BackendFactory"
        raise TypeError(msg)
    descriptor = factory.descriptor
    if descriptor.name != name:
        msg = f"descriptor name {descriptor.name!r} does not match registration name {name!r}"
        raise ValueError(msg)
    with self._lock:  # check + insert atomically: one winner per name
        if name in self._factories:
            raise BackendAlreadyRegisteredError(name)
        self._factories[name] = factory

suffixes

suffixes(*, installed_only: bool = True) -> set[str]

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
def suffixes(self, *, installed_only: bool = True) -> set[str]:
    """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.
    """
    suffixes: set[str] = set()
    for descriptor in self.list_backends():
        suffixes |= self.suffixes_for(descriptor, installed_only=installed_only)
    return suffixes

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
@staticmethod
def suffixes_for(descriptor: BackendDescriptor, *, installed_only: bool = True) -> set[str]:
    """The suffixes ONE descriptor can ingest — the per-backend half of :meth:`suffixes`."""
    if installed_only and not _extra_installed(descriptor):
        return set()

    formats = descriptor.capabilities.supported_formats
    return {suffix for suffix, media_type in _media_types().items() if media_type in formats}

supported_formats

supported_formats() -> list[str]

Sorted union of every registered backend's supported formats.

Source code in src/parsecraft/backends/registry.py
102
103
104
105
def supported_formats(self) -> list[str]:
    """Sorted union of every registered backend's supported formats."""
    formats = {fmt for descriptor in self.list_backends() for fmt in descriptor.capabilities.supported_formats}
    return sorted(formats)

BackendResult

Bases: BaseModel

Converged IR output of DocumentBackend.convert.

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.

DependencyUnavailableError

DependencyUnavailableError(module: str, extra: str)

Bases: BackendError

A backend's optional implementation module is not installed.

Source code in src/parsecraft/backends/errors.py
44
45
46
47
def __init__(self, module: str, extra: str) -> None:
    self.module = module
    self.extra = extra
    super().__init__(f"backend dependency {module!r} is not installed — install the {extra!r} extra")

DocumentBackend

Bases: Protocol

A backend: analyzes a source and converts bounded slices of it.

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
def analyze(self, source: SourceDocument) -> AnalysisResult:
    """Collect deterministic signals without converting content."""
    ...

convert

convert(request: ConversionRequest) -> BackendResult

Convert the requested slice into canonical IR pages.

Source code in src/parsecraft/backends/protocol.py
219
220
221
def convert(self, request: ConversionRequest) -> BackendResult:
    """Convert the requested slice into canonical IR pages."""
    ...

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.

coerce_option_value

coerce_option_value(value: str | int | float | bool) -> str | int | float | bool

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
def coerce_option_value(value: str | int | float | bool) -> str | int | float | bool:
    """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.
    """
    if not isinstance(value, str):
        return value
    lowered = value.strip().lower()
    if lowered in _TRUE_TOKENS:
        return True
    if lowered in _FALSE_TOKENS:
        return False
    try:
        return int(value)
    except ValueError:
        pass
    try:
        return float(value)
    except ValueError:
        return value

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 appends caption_of relations 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 exact source_span with 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_captions produced no attributions from the endpoint.

  • CaptionReport –

    Outcome of :func:attribute_captions — counts, never document content.

  • ChoiceAnswer –

    Public seam: the SDK's typed choice answer (.choices values).

  • 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_sdk module surface, imported at call time.

Functions:

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.

CaptionReport dataclass

CaptionReport(attributed: int, abstained: int, failure: CaptionFailure | None = None)

Outcome of :func:attribute_captions — counts, never document content.

ChoiceAnswer

Bases: Protocol

Public seam: the SDK's typed choice answer (.choices values).

SystemOneClient

Bases: Protocol

Public seam: the SDK client surface this module drives.

SystemOneResponse

Bases: Protocol

Public seam: the SDK's typed System One response.

SystemOneSdk

Bases: Protocol

Public seam: the typesafe_sdk module surface, imported at call time.

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
def 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.
    """
    pairs = _candidate_pairs(document)
    if not pairs:
        return CaptionReport(attributed=0, abstained=0)
    resolved = _resolve_endpoint(model)
    if isinstance(resolved, CaptionFailure):
        return CaptionReport(attributed=0, abstained=0, failure=resolved)
    api_key, model_token, base_url = resolved
    try:
        sdk = cast(SystemOneSdk, import_module(_SDK_MODULE_NAME))
        state_pairs: list[dict[str, object]] = []
        questions: dict[str, object] = {}
        for index, pair in enumerate(pairs):
            target_text, target_cut = _truncate(pair.target_text, _MAX_TARGET_CHARS)
            candidate_text, candidate_cut = _truncate(pair.paragraph_text, _MAX_CANDIDATE_CHARS)
            state_pairs.append(
                {
                    "target_kind": pair.target_kind,
                    "target_text": target_text,
                    "target_truncated": target_cut,
                    "candidate_text": candidate_text,
                    "candidate_truncated": candidate_cut,
                }
            )
            questions[f"pair_{index}"] = sdk.Choice(
                instructions=_question_instructions(index, pair, target_cut, candidate_cut),
                criteria=_choice_criteria(),
            )
    except Exception:
        return CaptionReport(attributed=0, abstained=0, failure=CaptionFailure.UNAVAILABLE)
    try:
        client_factory = _open_client(api_key=api_key, model=model_token, base_url=base_url)
    except Exception:
        return CaptionReport(attributed=0, abstained=0, failure=CaptionFailure.UNAVAILABLE)
    try:
        with client_factory as client:
            response = client.system_one({"pairs": state_pairs}, questions)
        choices = response.choices
    except Exception:
        return CaptionReport(attributed=0, abstained=0, failure=CaptionFailure.TRANSPORT_ERROR)
    attributed_pairs, abstained = _valid_attributions(pairs, choices)
    for pair in attributed_pairs:
        paragraph = document.pages[pair.page_index].blocks[pair.paragraph_index]
        paragraph.relations.append(ChunkRelation(kind=RelationKind.CAPTION_OF, target_id=pair.target_id))
    return CaptionReport(attributed=len(attributed_pairs), abstained=abstained)
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
def 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.
    """
    linked = 0
    for page in document.pages:
        for position, chunk in enumerate(page.blocks):
            if chunk.kind is not ChunkKind.CAPTION or chunk.source_span is None:
                continue
            neighbours: list[StructuredChunk] = []
            if position > 0:
                neighbours.append(page.blocks[position - 1])
            if position + 1 < len(page.blocks):
                neighbours.append(page.blocks[position + 1])
            for neighbour in neighbours:
                if not _target_role(neighbour.kind) or neighbour.source_span != chunk.source_span:
                    continue
                if _already_linked(chunk, neighbour.id):
                    continue
                chunk.relations.append(ChunkRelation(kind=RelationKind.CAPTION_OF, target_id=neighbour.id))
                linked += 1
    return linked