Perception
Parse
client.documents.parse(source, **options)
| Parameter | Type | Required | Description |
|---|---|---|---|
source | str | UrlSource | WorkspaceFileSource | ParseResultSource | Yes | The document to parse. |
page_ranges | list[dict] | No | One-based, inclusive ranges, such as [{"start": 1, "end": 3}]. Not with a parse_result source. Default: all pages. |
parse_mode | "low" / "medium" / "high" | No | Effort. low uses native OCR, medium routes to the best parser, high adds page verification and correction. Default: "low", the only value a parse_result source takes. |
output | dict | No | What the result holds and how. See output. |
figures | dict | No | What to do with figures. See figures. |
diagrams | dict | No | Whether to rewrite flowchart-like figures. See diagrams. |
chunking | dict | No | Split the result into pieces for retrieval. See chunking. |
spreadsheet | dict | No | Which sheets, hidden parts and formulas to read. Not with a parse_result source. See spreadsheet. |
password | str | No | Password for an encrypted PDF. Never stored or returned, and masked in the SDK's logs. Not with a parse_result source. |
Each dict option takes these keys:
output
| Key | Type | Default | Description |
|---|---|---|---|
output.formats | list[str] | ["markdown", "blocks"] | What to return: "markdown", "blocks" and "text". |
output.table_format | "html" / "markdown" | "html" | How tables are written in the Markdown and blocks. |
output.include_images | bool | False | Include the page images. Not with a parse_result source. |
output.include_page_markers | bool | True | Insert page markers between pages. |
output.return_ocr_data | bool | False | Return word and line OCR geometry. PDF sources only. |
figures
| Key | Type | Default | Description |
|---|---|---|---|
figures.mode | "include" / "omit" / "describe" | "include" | Keep the figures, drop them, or caption each one with a vision call. |
diagrams
| Key | Type | Default | Description |
|---|---|---|---|
diagrams.mode | "omit" / "mermaid" | "omit" | Leave diagrams alone, or rewrite flowchart-like figures as Mermaid. |
chunking
| Key | Type | Default | Description |
|---|---|---|---|
chunking.strategy | "none" / "page" / "section" | "none" | How to split the result into pieces sized for retrieval. |
spreadsheet
Not with a parse_result source.
| Key | Type | Default | Description |
|---|---|---|---|
spreadsheet.sheets | list[str] | All sheets | The names of the sheets to parse. |
spreadsheet.include_hidden_sheets | bool | True | Read sheets marked hidden. |
spreadsheet.include_hidden_rows | bool | True | Read rows marked hidden. |
spreadsheet.include_hidden_columns | bool | True | Read columns marked hidden. |
spreadsheet.include_formulas | bool | False | Include cell formulas. Needs table_format "html" and markdown or blocks output. |
A parse_result source with any of the options marked "not with a parse_result source" set to something other than its default (for spreadsheet: sheets, an include_hidden_* of False, or include_formulas=True), or with a parse_mode other than low, is refused with 422 (NaceUnprocessableEntityError) before a job is created. OCR runs when the file needs it: the document service refuses any ocr setting other than the default with 422 invalid_request.
from nace_sdk import NaceClient
with NaceClient() as client:
job = client.documents.parse(
"https://example.com/report.pdf",
page_ranges=[{"start": 1, "end": 3}],
output={"formats": ["markdown", "blocks"]},
chunking={"strategy": "page"},
wait_seconds=60,
)
if job.status != "succeeded":
job = client.jobs.wait(job.job_id)
print(job.result["document"]["markdown"])For a very large file, document.markdown is only a preview and document.content_url links the full text: save it with jobs.download. See Parse for the result shape.