Perception
Extract
client.documents.extract(source, *, schema=None, schema_id=None, schema_version=None, instructions=None, **options)
| Parameter | Type | Required | Description |
|---|---|---|---|
source | str | UrlSource | WorkspaceFileSource | ParseResultSource | Yes | The document to extract from. Reuse a finished parse with ParseResultSource so it isn't parsed and paid for twice. |
schema | dict | Yes, or schema_id | The fields to extract, as a JSON Schema. |
schema_id | str | Yes, or schema | A saved schema's id (sch_...). |
schema_version | int | No | The saved schema's version to use. Only with schema_id. Default: its latest version. |
instructions | str | No | Extra guidance for filling the declared fields. Can't add fields the schema doesn't list. |
page_ranges | list[dict] | No | One-based, inclusive ranges. Not with a parse_result source. Default: all pages. |
citations | dict | No | Where each field was read from. See citations. |
parse_mode | "low" / "medium" / "high" | No | Effort of the parse Extract runs first. Default: "low", the only value a parse_result source takes. |
Pass exactly one of schema and schema_id. Both, neither, or a schema_version without schema_id raises NaceError before anything is sent.
citations
| Key | Type | Default | Description |
|---|---|---|---|
citations.enabled | bool | True | Say where in the document each field was read. |
citations.include_source_text | bool | True | Add a short quote from the source. |
from nace_sdk import NaceClient, ParseResultSource
with NaceClient() as client:
parsed = client.jobs.wait(client.documents.parse("https://example.com/invoice.pdf").job_id)
job = client.documents.extract(
ParseResultSource(job_id=parsed.job_id),
schema={
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"total": {"type": "number"},
},
"required": ["invoice_number", "total"],
},
wait_seconds=60,
)
if job.status != "succeeded":
job = client.jobs.wait(job.job_id)
print(job.result["data"]) # {'invoice_number': 'INV-1042', 'total': 1200.5}See Extract for the result: data, shaped by your schema, and fields, one entry per schema field with its path, value, status (found, not_found or ambiguous), confidence and citations.