datalab-python-sdk 0.5.0__tar.gz → 0.6.0__tar.gz

datalab_python_sdk-0.6.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: Unit tests
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14", "3.15"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --group dev --frozen
+      - name: Lint
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+      - name: Run tests
+        run: uv run pytest tests/

{datalab_python_sdk-0.5.0 → datalab_python_sdk-0.6.0}/.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 repos:
 - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
-  rev: v0.12.3
+  rev: v0.17.1
   hooks:
     # Run the linter.
     - id: ruff-check

datalab_python_sdk-0.6.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+The newest release is at the top. Each export to this repository uses the
+top section as its commit message.
+
+## 0.6.0
+
+Breaking changes:
+
+- The SDK requires Python 3.11 or later. Python 3.10 reached end of life in
+  October 2026.
+- `ExtractOptions.mode` now defaults to `None`. The SDK sends `mode` only when
+  you set it, so the API picks the parse mode from `extraction_mode`. To keep
+  the old behavior, set `mode="fast"`.
+- App-only evaluation controls are no longer accepted by SDK calls.
+
+New:
+
+- **Open beta:** `run_agent()` and the `agent` CLI command run existing
+  published processors. Processor design is not included.
+- `form_fields()`, `generate_extraction_schemas()` and `delete_result()`,
+  each with a sync version on `DatalabClient`.
+- Convert options: `merge_cross_page`, `word_bboxes`, `disable_html_prettify`,
+  `exact_transcription`, `keep_pageheader_in_output` and
+  `keep_pagefooter_in_output`.
+- `processing_location` on the extract, segment, custom processor, track
+  changes, OCR, fill, document and upload calls.
+- `run_pipeline()` sends `checkpoint_id` and `processing_location`.
+  `create_pipeline()` accepts `reuse_draft`.
+- CLI commands `fill` and `form-fields`, and CLI flags for the new
+  convert and extract options.
+
+Fixes:
+
+- API errors keep the message from the API and map HTTP errors to exception
+  classes.
+- The SDK downloads signed result URLs and keeps result fields that it
+  dropped before.
+- The User-Agent header and `datalab --version` show the installed version.
+- The CLI `--skip_cache` option is a flag. `--format` accepts a
+  comma-separated list.
+
+Deprecated:
+
+- The workflow methods, because the API no longer serves workflows. Use
+  pipelines.
+- `run_custom_processor()`. Use `run_agent()`.

datalab_python_sdk-0.6.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.5
+Name: datalab-python-sdk
+Version: 0.6.0
+Summary: SDK for the Datalab document intelligence API
+Project-URL: Homepage, https://www.datalab.to
+Project-URL: Documentation, https://documentation.datalab.to
+Project-URL: Repository, https://github.com/datalab-to/sdk
+Author-email: Datalab Team <hi@datalab.to>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,datalab,document-intelligence,sdk
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.12.14
+Requires-Dist: click>=8.2.1
+Requires-Dist: ijson>=3.3.0
+Requires-Dist: pydantic-settings>=2.10.1
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: tenacity>=8.2.3
+Requires-Dist: tqdm>=4.66.0
+Description-Content-Type: text/markdown
+
+# Datalab SDK
+
+A Python SDK for the [Datalab API](https://www.datalab.to/?utm_source=gh-sdk) - it turns documents into verifiable knowledge your agents act on. Datalab is the team behind [Chandra](https://github.com/datalab-to/chandra), [marker](https://github.com/datalab-to/marker), [surya](https://github.com/datalab-to/surya), and [lift](https://github.com/datalab-to/lift).
+
+See the full documentation at [https://documentation.datalab.to](https://documentation.datalab.to).
+
+## Installation
+
+```bash
+pip install datalab-python-sdk
+```
+
+## Quick Start
+
+### Authentication
+
+[Sign up](https://www.datalab.to/?utm_source=gh-sdk), then get your API key from [https://www.datalab.to/app/keys](https://www.datalab.to/app/keys):
+
+```bash
+export DATALAB_API_KEY="your_api_key_here"
+```
+
+### Basic Usage
+
+```python
+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
+
+```python
+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](https://documentation.datalab.to/api-reference/convert-document) describes each option.
+
+## Structured extraction
+
+```python
+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](https://documentation.datalab.to/docs/welcome/sdk/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:
+
+```bash
+# 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

datalab_python_sdk-0.6.0/README.md

@@ -0,0 +1,130 @@
+# Datalab SDK
+
+A Python SDK for the [Datalab API](https://www.datalab.to/?utm_source=gh-sdk) - it turns documents into verifiable knowledge your agents act on. Datalab is the team behind [Chandra](https://github.com/datalab-to/chandra), [marker](https://github.com/datalab-to/marker), [surya](https://github.com/datalab-to/surya), and [lift](https://github.com/datalab-to/lift).
+
+See the full documentation at [https://documentation.datalab.to](https://documentation.datalab.to).
+
+## Installation
+
+```bash
+pip install datalab-python-sdk
+```
+
+## Quick Start
+
+### Authentication
+
+[Sign up](https://www.datalab.to/?utm_source=gh-sdk), then get your API key from [https://www.datalab.to/app/keys](https://www.datalab.to/app/keys):
+
+```bash
+export DATALAB_API_KEY="your_api_key_here"
+```
+
+### Basic Usage
+
+```python
+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
+
+```python
+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](https://documentation.datalab.to/api-reference/convert-document) describes each option.
+
+## Structured extraction
+
+```python
+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](https://documentation.datalab.to/docs/welcome/sdk/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:
+
+```bash
+# 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

{datalab_python_sdk-0.5.0 → datalab_python_sdk-0.6.0}/datalab_sdk/__init__.py

@@ -6,7 +6,18 @@ supporting document conversion, extraction, segmentation, and more.
 """
 
 from .client import DatalabClient, AsyncDatalabClient
-from .exceptions import DatalabError, DatalabAPIError, DatalabTimeoutError
+from .exceptions import (
+    DatalabError,
+    DatalabAPIError,
+    DatalabAuthenticationError,
+    DatalabPaymentRequiredError,
+    DatalabNotFoundError,
+    DatalabRateLimitError,
+    DatalabServerError,
+    DatalabTimeoutError,
+    DatalabFileError,
+    DatalabValidationError,
+)
 from .models import (
     ConversionResult,
     CreateDocumentResult,
@@ -21,6 +32,11 @@ from .models import (
     OCROptions,
     FormFillingOptions,
     FormFillingResult,
+    FormFieldsOptions,
+    FormFieldsResult,
+    AgentOptions,
+    AgentResult,
+    ExtractionSchemaSuggestions,
     Workflow,
     WorkflowStep,
     WorkflowExecution,
@@ -43,7 +59,14 @@ __all__ = [
     "AsyncDatalabClient",
     "DatalabError",
     "DatalabAPIError",
+    "DatalabAuthenticationError",
+    "DatalabPaymentRequiredError",
+    "DatalabNotFoundError",
+    "DatalabRateLimitError",
+    "DatalabServerError",
     "DatalabTimeoutError",
+    "DatalabFileError",
+    "DatalabValidationError",
     "ConversionResult",
     "CreateDocumentResult",
     "FileResult",
@@ -57,6 +80,11 @@ __all__ = [
     "OCROptions",
     "FormFillingOptions",
     "FormFillingResult",
+    "FormFieldsOptions",
+    "FormFieldsResult",
+    "AgentOptions",
+    "AgentResult",
+    "ExtractionSchemaSuggestions",
     "Workflow",
     "WorkflowStep",
     "WorkflowExecution",