Python API

Generated from the source. For a guided introduction, see Python usage.

Top-level helpers

parse

parse(
    path,
    *,
    backend: str | None = None,
    mode: str = "balanced",
    fallback: bool | None = None,
    ocr: bool | None = None,
)

Synchronous convenience wrapper around Gateway().parse.

backend: "auto" (router decides) or an engine id; None uses $DOCTOPUS_BACKEND, else "auto".

chunk

chunk(
    path,
    *,
    max_chars: int = 1500,
    backend: str | None = None,
    mode: str = "balanced",
)

Parse then split into layout-aware chunks (list of doctopus.core.chunk.Chunk).

plan

plan(
    path,
    *,
    backend: str | None = None,
    mode: str = "balanced",
)

Routing decision only (no extraction).

Gateway

Gateway(
    max_bytes: int = MAX_BYTES,
    default_backend: str | None = None,
)

The single entry point. CLI, REST and MCP are thin wrappers around this.

default_backend: engine used when a request does not name one ("auto" = let the router decide). Falls back to $DOCTOPUS_BACKEND, then "auto". A request that names an engine (or "auto") always wins.

parse async

parse(
    path: str | Path,
    *,
    backend: str | None = None,
    mode: Mode = "balanced",
    fallback: bool | None = None,
    ocr: bool | None = None,
) -> Document

plan

plan(
    path: str | Path,
    *,
    backend: str | None = None,
    mode: Mode = "balanced",
) -> Decision

Routing decision only -- nothing is extracted.

list_backends

list_backends()

Document schema

Canonical, versioned output contract. Unknown values stay None -- never fabricated.

SCHEMA_VERSION module-attribute

SCHEMA_VERSION = '1.0'

Document

Bases: BaseModel

schema_version class-attribute instance-attribute

schema_version: str = SCHEMA_VERSION

meta instance-attribute

meta: DocMeta

markdown instance-attribute

markdown: str

text instance-attribute

text: str

blocks class-attribute instance-attribute

blocks: list[Block] = Field(default_factory=list)

tables class-attribute instance-attribute

tables: list[Table] = Field(default_factory=list)

pages class-attribute instance-attribute

pages: list[Page] = Field(default_factory=list)

processing instance-attribute

processing: Processing

DocMeta

Bases: BaseModel

document_id instance-attribute

document_id: str

filename instance-attribute

filename: str

format instance-attribute

format: str

mime_type class-attribute instance-attribute

mime_type: str | None = None

page_count class-attribute instance-attribute

page_count: int | None = None

size_bytes instance-attribute

size_bytes: int

content_hash instance-attribute

content_hash: str

title class-attribute instance-attribute

title: str | None = None

processed_at class-attribute instance-attribute

processed_at: datetime = Field(
    default_factory=lambda: datetime.now(timezone.utc)
)

Block

Bases: BaseModel

id instance-attribute

id: str

type instance-attribute

type: str

text instance-attribute

text: str

page class-attribute instance-attribute

page: int | None = None

bbox class-attribute instance-attribute

bbox: Bbox | None = None

level class-attribute instance-attribute

level: int | None = None

source instance-attribute

source: str

Table

Bases: BaseModel

id instance-attribute

id: str

page class-attribute instance-attribute

page: int | None = None

markdown instance-attribute

markdown: str

rows class-attribute instance-attribute

rows: list[list[str]] | None = None

bbox class-attribute instance-attribute

bbox: Bbox | None = None

source instance-attribute

source: str

Page

Bases: BaseModel

page instance-attribute

page: int

text instance-attribute

text: str

Bbox

Bases: BaseModel

x0 instance-attribute

x0: float

y0 instance-attribute

y0: float

x1 instance-attribute

x1: float

y1 instance-attribute

y1: float

Processing

Bases: BaseModel

backend instance-attribute

backend: str

backend_version class-attribute instance-attribute

backend_version: str | None = None

mode instance-attribute

mode: Mode

elapsed_ms instance-attribute

elapsed_ms: int

peak_rss_mb class-attribute instance-attribute

peak_rss_mb: float | None = None

ocr_used class-attribute instance-attribute

ocr_used: bool | None = None

fallback_from class-attribute instance-attribute

fallback_from: str | None = None

warnings class-attribute instance-attribute

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

decision class-attribute instance-attribute

decision: Decision | None = None

Decision

Bases: BaseModel

Why the router chose what it chose -- shown in CLI, API, MCP and the UI.

backend instance-attribute

backend: str

mode instance-attribute

mode: Mode

reasons instance-attribute

reasons: list[str]

inspection class-attribute instance-attribute

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

BackendInfo

Bases: BaseModel

id instance-attribute

id: str

version class-attribute instance-attribute

version: str | None = None

available instance-attribute

available: bool

reason_unavailable class-attribute instance-attribute

reason_unavailable: str | None = None

formats instance-attribute

formats: list[str]

capabilities instance-attribute

capabilities: dict[str, bool]

weight instance-attribute

weight: Literal['light', 'heavy']

ram_mb class-attribute instance-attribute

ram_mb: int | None = None

licence class-attribute instance-attribute

licence: str | None = None

runtime class-attribute instance-attribute

runtime: Literal["in-process", "sidecar", "service"] = (
    "in-process"
)

Chunks

Layout-aware chunking for RAG and dataset export. A pure function over the canonical Document.

Rules: a heading closes the current chunk and becomes context (heading_path) for the next ones; text blocks are packed up to max_chars and over-long ones split at sentence boundaries; tables are always whole chunks placed in page order; page headers/footers are dropped. Chunk ids are deterministic (content hash + ordinal), so re-running over the same file gives the same ids.

Chunk

Bases: BaseModel

id instance-attribute

id: str

kind instance-attribute

kind: Literal['text', 'table']

text instance-attribute

text: str

n_chars instance-attribute

n_chars: int

heading_path instance-attribute

heading_path: list[str]

pages instance-attribute

pages: list[int]

block_ids class-attribute instance-attribute

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

table_id class-attribute instance-attribute

table_id: str | None = None

source instance-attribute

source: ChunkSource

ChunkSource

Bases: BaseModel

filename instance-attribute

filename: str

document_id instance-attribute

document_id: str

content_hash instance-attribute

content_hash: str

backend instance-attribute

backend: str

schema_version class-attribute instance-attribute

schema_version: str = SCHEMA_VERSION

chunk

chunk(
    doc: Document, *, max_chars: int = MAX_CHARS
) -> list[Chunk]

Errors

Every error carries a stable code, which the REST API and MCP tools return in their error payloads.

DoctopusError

Bases: Exception

Base class; carries a stable code for API/MCP error payloads.

code class-attribute instance-attribute

code = 'doctopus_error'

BackendUnavailable

Bases: DoctopusError

code class-attribute instance-attribute

code = 'backend_unavailable'

UnsupportedFormat

Bases: DoctopusError

code class-attribute instance-attribute

code = 'unsupported_format'

ExtractionFailed

Bases: DoctopusError

code class-attribute instance-attribute

code = 'extraction_failed'

InputRejected

Bases: DoctopusError

code class-attribute instance-attribute

code = 'input_rejected'

Backend protocol

Adapters implement this protocol and return a RawResult, which the gateway wraps into a Document.

Backend

Bases: Protocol

id instance-attribute

id: str

info

info() -> BackendInfo

supports

supports(ext: str) -> bool

process async

process(
    path: Path, *, ocr: bool | None = None
) -> RawResult

RawResult dataclass

RawResult(
    markdown: str,
    text: str,
    blocks: list[Block] = list(),
    tables: list[Table] = list(),
    pages: list[Page] = list(),
    page_count: int | None = None,
    title: str | None = None,
    mime_type: str | None = None,
    ocr_used: bool | None = None,
    quality: float | None = None,
    warnings: list[str] = list(),
)

What an adapter returns; the Gateway wraps it into a canonical Document.

markdown instance-attribute

markdown: str

text instance-attribute

text: str

blocks class-attribute instance-attribute

blocks: list[Block] = field(default_factory=list)

tables class-attribute instance-attribute

tables: list[Table] = field(default_factory=list)

pages class-attribute instance-attribute

pages: list[Page] = field(default_factory=list)

page_count class-attribute instance-attribute

page_count: int | None = None

title class-attribute instance-attribute

title: str | None = None

mime_type class-attribute instance-attribute

mime_type: str | None = None

ocr_used class-attribute instance-attribute

ocr_used: bool | None = None

quality class-attribute instance-attribute

quality: float | None = None

warnings class-attribute instance-attribute

warnings: list[str] = field(default_factory=list)