Skip to main content

Datalab SDK

A Python SDK for the Datalab API - it turns documents into verifiable knowledge your agents act on. Datalab is the team behind Chandra, marker, surya, and lift.

See the full documentation at https://documentation.datalab.to.

Installation

pip install datalab-python-sdk

Quick Start

Authentication

Sign up, then get your API key from https://www.datalab.to/app/keys:

export DATALAB_API_KEY="your_api_key_here"

Or sign in from a terminal, which also works for coding agents:

datalab login

It shows a code and a link. Open the link, sign in or sign up, approve the code, and type the 6-digit code that we email you. The SDK saves the key to ~/.config/datalab/config.json, readable only by your user, and uses it when DATALAB_API_KEY is not set. datalab logout deletes it.

Basic Usage

from datalab_sdk import DatalabClient

client = DatalabClient() # use env var from above, or pass api_key="your_api_key_here"

# Convert PDF to markdown
result = client.convert("document.pdf")
print(result.markdown)

AsyncDatalabClient has the same methods as DatalabClient, as coroutines.

Conversion options

from datalab_sdk import ConvertOptions

options = ConvertOptions(
    mode="balanced",               # lite, fast, balanced, accurate (SDK default: fast)
    output_format="markdown,html", # markdown, html, json, chunks (comma-separated)
    page_range="0-4",
    extras="chart_understanding,table_cell_bboxes",
    merge_cross_page=True,         # merge tables, paragraphs and lists split across pages
    word_bboxes=True,              # per-word bounding boxes in the HTML output
    save_checkpoint=True,          # reuse the parse in extract() or segment()
)
result = client.convert("document.pdf", options=options)

Other options include paginate, add_block_ids, disable_html_prettify, exact_transcription, token_efficient_markdown, include_markdown_in_chunks, disable_image_extraction, disable_image_captions, fence_synthetic_captions, keep_spreadsheet_formatting, keep_pageheader_in_output, keep_pagefooter_in_output, additional_config, webhook_url, skip_cache and processing_location. The API reference describes each option.

Structured extraction

from datalab_sdk import ExtractOptions

result = client.extract(
    "invoice.pdf",
    options=ExtractOptions(
        page_schema='{"properties": {"total": {"type": "number"}}}',  # or schema_id="sch_..."
        extraction_mode="balanced",  # turbo, fast, balanced, accurate
    ),
)
print(result.extraction_schema_json, result.extraction_score_average)

When you do not set the parse mode, the API picks the parse mode that matches extraction_mode.

Other endpoints

Method Endpoint
run_agent() Beta: run an existing published processor (AgentOptions(processor="cp_..."))
segment() Split a document into sections (SegmentOptions)
fill() Fill a PDF or image form (FormFillingOptions)
form_fields() Find the fillable fields in a PDF or image
track_changes() Read tracked changes and comments from DOCX or PDF
create_document() Make a DOCX from markdown with track changes markup
generate_extraction_schemas() Suggest extraction schemas for a saved checkpoint
delete_result() Result deletion, by result.request_id
upload_files(), list_files(), ... File storage. Pass the returned datalab://file-... reference as file_url
create_extraction_schema(), ... Saved extraction schemas
create_pipeline(), run_pipeline(), ... Pipelines

run_custom_processor() and ocr() call deprecated API endpoints. Use run_agent() and convert() instead.

Published-agent execution is in open beta; the API may change. Processor design and raw-prompt execution are not included.

Inputs, polling and errors

  • Send a local file with file_path, or a URL or a datalab://file-... reference with file_url. When you set processing_location, send the document as file_url.
  • Processing methods poll until the result is ready. Set max_polls and poll_interval to change the limit (default: 300 polls, 1 second apart). Use stream_response_to to write a large result straight to disk.
  • The SDK retries a submission that gets HTTP 429 or 503, and polls that get 408, 429, 5xx or a connection error. It waits for the Retry-After header when the API sends one.
  • API errors raise DatalabAPIError (with status_code and response_data) or one of its subclasses: DatalabAuthenticationError (401, 403), DatalabPaymentRequiredError (402), DatalabNotFoundError (404), DatalabRateLimitError (429) and DatalabServerError (5xx). Invalid arguments raise DatalabValidationError, which is also a ValueError.

Workflows

The Datalab API removed the Workflows API. The workflow methods and CLI commands in this SDK are deprecated, and the API does not answer them. Use pipelines instead.

CLI Usage

The SDK includes a command-line interface:

# Convert a document or a directory of documents
datalab convert document.pdf --mode balanced --format markdown,html

# Extract with a saved schema
datalab extract invoice.pdf --schema_id sch_XXXXX --extraction_mode fast

# Other commands
datalab agent --help
datalab segment --help
datalab fill --help
datalab form-fields --help
datalab track-changes --help
datalab create-document --help

Contributing

Issues and bug reports are welcome here. We develop the SDK in a private repository and mirror each release to this one, so we do not merge pull requests here directly. Open an issue, or open a pull request to show the change, and we will port it and credit you.

License

MIT License

Metadata

Release files for datalab-python-sdk 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for datalab-python-sdk 0.7.0
File Size Uploaded Provenance Actions
datalab_python_sdk-0.7.0.tar.gz 2.0 MB Without provenance Details for datalab_python_sdk-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for datalab-python-sdk 0.7.0
File Interpreter ABI Platform Actions
datalab_python_sdk-0.7.0-py3-none-any.whl Python 3 none any Details for datalab_python_sdk-0.7.0-py3-none-any.whl

Total release size: 2.0 MB

Release files / datalab_python_sdk-0.7.0.tar.gz

Download URL datalab_python_sdk-0.7.0.tar.gz
Size 2.0 MB
Tags Source
SHA-256 checksum
How to use checksums
822566a6b354c28e2fe57b9a3239690838d7621a176b6de8edcbc92f8d57be4b
BLAKE2b-256 checksum
How to use checksums
782510df1dcd689b59a308662ed18955d22251016da03f5ce3ec999c5f50965c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / datalab_python_sdk-0.7.0-py3-none-any.whl

Download URL datalab_python_sdk-0.7.0-py3-none-any.whl
Size 47.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
27e288d81fdf9d7cd84dc0c26882c976460b39d67076eb3f0dabcc3762282c7b
BLAKE2b-256 checksum
How to use checksums
1e055a67a5f85e28a1d7c0e81397bee67c2940a1b6ac7587815011bb4ca2be6d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for datalab-python-sdk 0.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.7.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page