OpenDocs

OpenDocs is a Python SDK that converts caller-provided local documents into Markdown. The 0.1.0 Alpha supports TXT, Markdown, standalone images, native/hybrid/visual PDF parsing, and native DOCX/PPTX extraction through stable sync/async APIs.

The Python distribution name is opendocs-sdk, while the import package remains opendocs.

pip install opendocs-sdk==0.1.0

Install from an existing checkout

From a separate consuming project, point the dependency at a local OpenDocs checkout that contains pyproject.toml. The examples below assume your consumer project and the OpenDocs checkout are sibling directories, so ../OpenDocs resolves to this checkout. These commands were verified against a local checkout flow; do not assume the current remote default branch is installable.

uv add ../OpenDocs

pip install ../OpenDocs

Quick start

Synchronous local-path example:

from opendocs import parse

markdown = parse("notes.md")

Asynchronous bytes example:

import asyncio

from opendocs import aparse


async def main() -> str:
    markdown = await aparse(b"plain text")
    return markdown


markdown = asyncio.run(main())

Accepted inputs:

• local filesystem path as str
• local filesystem path as os.PathLike[str]
• bytes
• binary file object with read() -> bytes

Callers own all remote downloads. http://, https://, oss://, and s3:// sources must be downloaded before calling OpenDocs.

Current behavior

parse() and aparse() return Markdown strings only. Image and visual PDF work uses the provider-neutral LiteLLM adapter when a VisionConfig is supplied. Native and blank PDF pages do not call a model or invoke Poppler. Poppler's pdftoppm executable is checked lazily only when a PDF page must be rasterized for hybrid or full-vision parsing.

Install Poppler with your platform package manager before parsing visual PDFs (for example, brew install poppler on macOS or apt-get install poppler-utils on Debian/Ubuntu). Pillow, pdfplumber, LiteLLM, python-docx, and python-pptx are installed as Python dependencies of opendocs-sdk.

from opendocs import ParseOptions, VisionConfig, parse

markdown = parse(
    "scan.pdf",
    options=ParseOptions(timeout=300, max_pages=100, vision_concurrency=4),
    vision=VisionConfig(
        model="openai/gpt-4o-mini",
        api_key="...",  # Prefer an environment-backed secret in production.
    ),
)

Standalone images require VisionConfig. PDFs and Office documents without vision configuration preserve usable native content and emit deterministic warnings for visual regions; a document with no usable native content raises VisionRequiredError. Model authentication, permission, invalid request, temporary unavailability, and invalid response failures use distinct typed exceptions. ParseOptions bounds the document timeout, PPTX/PDF page count, complete-block output size, and visual concurrency.

ParseOptions.vision_concurrency limits visual requests within one parse. Applications control cross-document concurrency themselves, for example with an asyncio.Semaphore; see the independent consumer example. OpenDocs does not provide a process-wide semaphore, model-call/token/currency cap, or performance SLA.

DOCX extraction preserves authored body paragraphs, headings, lists, safe links, tables, merged cells, explicit page breaks, and inline raster-image positions. A DOCX remains one continuous logical flow; max_pages does not infer physical Word pages. PPTX extraction emits every slide boundary and traverses each slide's shape tree in source order, including recursive groups, text, tables, accessible chart data, and raster pictures. Exact duplicate embedded images are analyzed once per parse and replayed at every authored slot.

Current format matrix

The release-blocking platform matrix is Ubuntu and macOS on Python 3.11, 3.12, and 3.13, with Poppler installed. Windows is unverified for 0.1.0 and is not claimed as supported or broken.

OpenDocs never downloads HTTP, OSS, or S3 URLs, including Office hyperlink targets and external relationships. Model calls may send sanitized images to the provider selected by VisionConfig; review that provider's privacy and cost terms before enabling vision.

Warnings and errors

OpenDocs uses Python warnings for recoverable degradation and typed exceptions for fatal failures.

import warnings

from opendocs import OpenDocsError, OpenDocsWarning, ParseOptions, parse

with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always", OpenDocsWarning)
    markdown = parse(
        b"first paragraph\n\nsecond paragraph\n",
        options=ParseOptions(max_output_chars=16),
    )

assert markdown == "first paragraph\n"
assert caught[0].message.code == "output_truncated"

try:
    parse("slides.pdf")
except OpenDocsError as error:
    print(error.code, error.retryable)

Project docs

• Documentation
• Roadmap
• Contributing
• License