Perception
Classify
client.documents.classify(source, *, classes, **options)
| Parameter | Type | Required | Description |
|---|---|---|---|
source | str | UrlSource | WorkspaceFileSource | Yes | The document to classify. Doesn't take a parse_result source. |
classes | list[dict] | Yes | Your labels. See classes. |
granularity | "document" / "page" | No | Score the whole file once, or once per page. Default: "document". |
page_ranges | list[dict] | No | One-based, inclusive ranges to read and classify. Not for workbooks. Default: all pages. |
unknown_policy | "allow" / "force_best" | No | allow (default) may mark a unit unknown; force_best commits an ambiguous unit to one of your classes. |
output | dict | No | How many labels, and whether each has a reason. See output. |
parse_mode | "low" / "medium" / "high" | No | Effort of the parse Classify runs first. Default: "low". |
Each dict option takes these keys:
classes
One entry per label, each a dict:
| Key | Type | Default | Description |
|---|---|---|---|
classes[].id | str | Required | The label's id, returned on the results. |
classes[].label | str | Required | The label's name. |
classes[].description | str | "" | What belongs in the class. |
classes[].criteria | list[str] | None | Extra rules to apply when scoring this class. |
classes[].subclasses | list[dict] | None | Finer labels under this class, each with subclasses[].id and subclasses[].label (both required), and an optional subclasses[].description and subclasses[].criteria. |
output
| Key | Type | Default | Description |
|---|---|---|---|
output.max_alternatives | int | 3 | The ranked labels to return per unit, from 1 to 10. |
output.include_reason | bool | True | Add a short reason to each label. |
from nace_sdk import NaceClient
with NaceClient() as client:
job = client.documents.classify(
"https://example.com/invoice.pdf",
classes=[
{"id": "invoice", "label": "Invoice", "description": "A supplier invoice"},
{"id": "contract", "label": "Contract", "description": "A signed agreement between two parties"},
],
granularity="page",
wait_seconds=60,
)
if job.status != "succeeded":
job = client.jobs.wait(job.job_id)
for unit in job.result["units"]:
print(unit["page_range"], unit["labels"][0]["class_id"])Class ids must be unique and can't contain /, and other, blank_page, unreadable_content and __ndi_unclassified are reserved. See Classify.