docling-carve

Convert Docling documents to Carve with provenance, image assets, and diagnostics for content that needs review. Use the Python API, command line, HTTP, or MCP interface. All interfaces share the same exporter and report contract.

The package owns its native wrapper over carve-lang 0.1.12. It does not require carve-py or an unreleased Python binding API. Python 3.10 or newer is required.

Installation

The first release, 0.1.0, is being prepared. Until wheels are published, build from this repository with Rust and Python installed:

python -m venv .venv
. .venv/bin/activate
pip install maturin
maturin develop --release

After publication, install docling-carve. The core dependency is docling-core; the full extraction pipeline is optional. Extras are extract, http, and mcp. They can be combined, for example docling-carve[http,extract].

Python

from docling_core.types.doc import DoclingDocument, DocItemLabel
from docling_carve import export_docling

doc = DoclingDocument(name="report")
doc.add_heading("Report", level=1)
doc.add_text(label=DocItemLabel.PARAGRAPH, text="Reviewed content.")
result = export_docling(doc)
print(result.value)
result.write_bundle("report-bundle")

export_json(payload) accepts a Docling JSON object, string, or bytes. CarveDocSerializer and CarveSerializerProvider implement Docling's serializer interfaces. See the API guide.

Command line

docling-carve convert document.json -o document.crv --report report.json
docling-carve convert document.json --bundle report-bundle
docling-carve batch incoming --output-dir converted --keep-going
docling-carve convert report.pdf --extract --bundle report-bundle
docling-carve convert report.pdf --extract --pdf-pipeline native --bundle native-bundle

Bundles contain document.crv, report.json, ast.json, preview.html, extracted PNG assets, and docling.json. Existing outputs are refused. --force replaces a managed bundle only when it contains no unrelated files. Use --no-source-snapshot to omit the original document.

--strict refuses any conversion diagnostic and exits with status 2. Other failures use status 1. --format selects carve, report-json, ast-json, or html. JSON reports written to stdout include base64 assets.

HTTP and MCP

docling-carve serve --host 127.0.0.1 --port 8080
docling-carve mcp
docling-carve mcp --root ./incoming

HTTP accepts Docling JSON at POST /v1/convert, and uploaded document bytes at POST /v1/extract when extraction is installed. Set DOCLING_CARVE_TOKEN to require a bearer token. MCP runs over stdio; file extraction requires an explicit root. See service examples for JavaScript, PHP, and MCP clients.

Preservation limits

Reports always set complete: false. Conversion checks reading order, nested lists, formatting, table geometry, captions, assets, and available provenance. It cannot establish extraction accuracy, preserve visual layout, or verify downstream rendering. Unsupported roles and normalizations produce diagnostics. The original Docling snapshot retains information outside the Carve mapping.

Body content is exported by default. Other layers must be selected explicitly. Image files from JSON require a contained asset_root; remote image references are rejected. Resource limits cover input bytes, document items, table cells, image pixels, asset bytes, and retained diagnostics.

See mapping and compatibility, report schema, and development and release.