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.
Progress callbacks
With SDK 0.8.0 or later, pass on_progress to processing calls:
result = client.convert(
"document.pdf",
on_progress=lambda percent: print(f"Processing: {percent}%"),
)
The same argument works with extract, segment, run_agent, track_changes,
create_document, ocr, fill, and form_fields, including stream_response_to.
run_pipeline and get_pipeline_execution also support it; set max_polls
above 1 to keep polling a pipeline. Result models expose progress_percent
when the API supplies it.
Callbacks receive increasing integer percentages from existing polls, skipping
missing values and duplicates. Percentages may pause or jump and are not an ETA.
A callback receives 100 only after successful completion and any signed-result
download. Check the returned status and success to determine the outcome.
AsyncDatalabClient also accepts async callbacks, which it awaits. Keep callbacks
short: they run inline, and their exceptions propagate to your call. Callback
errors stop local polling; they do not cancel the server request. No extra API
requests are made, and polling intervals are unchanged.
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.
Open beta (SDK 0.9.2): set citation_granularity="phrase" in
ExtractOptions for matching words, offsets and match scores. A citation includes
a box only when the phrase can be located; some citations keep only block/page
references. Phrase citations cost nothing extra. Turbo returns no citations. See the
phrase citation guide.
Redaction
Open beta (SDK 0.9.0): the redaction API may change.
from datalab_sdk import RedactOptions
result = client.redact(
"document.pdf",
options=RedactOptions(preset="personal_information"),
)
# A PDF can be returned even when verification fails. Review these first.
print(result.verdict, result.failing_checks)
if result.success and result.verdict == "PASS" and not result.withheld and result.output_base64:
result.save_output("redacted.pdf")
get_redaction_presets() returns the built-in preset IDs and specifications.
Use redaction_spec to supply a custom spec. Redaction processes the whole
PDF or image; page subsets are not supported. Completed requests are charged
even if verification fails. save_output on redact() saves any available
PDF, including one with failed verification. Redaction returns a typed result;
stream_response_to is not supported for this helper.
Other endpoints
| Method | Endpoint |
|---|---|
run_agent() |
Beta: run an existing published processor (AgentOptions(processor="cp_..."), or built-in jats / wcag) |
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 |
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.
The published jats processor returns JATS XML; wcag returns an Accessible PDF.
Inspect finished, verdict and verifier_metrics before using either artifact.
Fixed processor examples
show the result fields and version pinning.
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 adatalab://file-...reference withfile_url. When you setprocessing_location, send the document asfile_url. - Processing methods poll until the result is ready. The first 8 seconds poll every 0.3 seconds. Set
max_pollsandpoll_intervalto change the limit (default: 300 polls, 1 second apart). Usestream_response_toto 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-Afterheader when the API sends one. - API errors raise
DatalabAPIError(withstatus_codeandresponse_data) or one of its subclasses:DatalabAuthenticationError(401, 403),DatalabPaymentRequiredError(402),DatalabNotFoundError(404),DatalabRateLimitError(429) andDatalabServerError(5xx). Invalid arguments raiseDatalabValidationError, which is also aValueError.
With SDK 0.9.0, upload_files(paths, max_concurrency=5) streams
files from disk and limits the number of active uploads. Results retain the
input order. Use AsyncDatalabClient inside an existing async event loop.
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.11.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| datalab_python_sdk-0.11.0.tar.gz | 2.0 MB | Without provenance | Details for datalab_python_sdk-0.11.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| datalab_python_sdk-0.11.0-py3-none-any.whl | Python 3 | none | any | Details for datalab_python_sdk-0.11.0-py3-none-any.whl |
Total release size: 2.1 MB
Release files / datalab_python_sdk-0.11.0.tar.gz
| Download URL | datalab_python_sdk-0.11.0.tar.gz |
|---|---|
| Size | 2.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3e933680bbed1764e5db330ae7da4bb294d8ef02486cf227f7a9132da844923b
|
|
BLAKE2b-256 checksum How to use checksums |
5b81e22e996bc115a39652a7f1e66fc0fbfd3a6f76cf2f1234e35f7c05b95daf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","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.11.0-py3-none-any.whl
| Download URL | datalab_python_sdk-0.11.0-py3-none-any.whl |
|---|---|
| Size | 59.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d34a26d00f026da62794aa637070d75736449bc015cb3b64ea4ba0c992abdedf
|
|
BLAKE2b-256 checksum How to use checksums |
9eb15de3976bb5593986ff6ee06716db934f0dbe6dce0aafcd04a4d855315a15
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","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.11.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.