Classify

documents.classify scores one original file against caller-defined classes. Classify the whole document once, or return one unit per selected page.

Classify reads the original file and does not accept ParseResultSource.

Basic usage

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import ClassifyClass

with NdiClient() as client:
    document = client.documents.create_upload("mailroom-scan.pdf")
    queued = client.documents.classify(
        document,
        classes=[
            ClassifyClass(
                id="invoice",
                label="Invoice",
                description="A supplier invoice requesting payment",
            ),
            ClassifyClass(
                id="contract",
                label="Contract",
                description="An agreement signed by two or more parties",
            ),
            ClassifyClass(
                id="bank_statement",
                label="Bank statement",
                description="Periodic account activity issued by a bank",
            ),
        ],
        wait_seconds=30,
    )
    job = client.jobs.wait(queued.job_id, timeout=600)
    # Returns: succeeded Job; job.result is a ClassifyResult

    for unit in job.result.units:
        print(unit.unknown, unit.labels)

Method signature

def classify(
    source: UploadSource | UrlSource | WorkspaceFileSource | UploadResponse,
    *,
    classes: list[ClassifyClass],
    granularity: Literal["document", "page"] = "document",
    page_ranges: list[PageRange] | None = None,
    parse_mode: Literal["low", "medium", "high"] = "low",
    unknown_policy: Literal["allow", "force_best"] = "allow",
    output: ClassifyOutputOptions | None = None,
    wait_seconds: int = 0,
    idempotency_key: str | None = None,
) -> Job

Parameters

Parameter	Type	Required	Description
`source`	upload, URL, or workspace file	Yes	Original file to classify. A prior parse job is not accepted
`classes`	`list[ClassifyClass]`	Yes	Caller-defined labels to score
`granularity`	`"document"` / `"page"`	No	Return one unit for the file or one unit per page
`page_ranges`	`list[PageRange]`	No	One-based inclusive ranges. Omit for the whole document
`parse_mode`	`"low"` / `"medium"` / `"high"`	No	Parsing effort applied before classification
`unknown_policy`	`"allow"` / `"force_best"`	No	`allow` may mark a unit unknown. `force_best` commits an ambiguous unit to a class, but blank, unreadable, unparsed, or never-read pages stay unknown
`output`	`ClassifyOutputOptions`	No	Alternative-label count and reason inclusion
`wait_seconds`	`int`	No	Hold the submission request open for up to 300 seconds
`idempotency_key`	`str`	No	Override the key the SDK normally mints

Unread pages are reported with a classification_unread_pages disclosure.

Returns

A Job. After success, job.result is a ClassifyResult containing units and any non-fatal disclosures. Unread pages are disclosed as classification_unread_pages.

Define classes

Each class has a stable id, display label, and model guidance:

from ndi_sdk.models.document_ops import ClassifyClass

classes = [
    ClassifyClass(
        id="invoice",
        label="Invoice",
        description="Supplier request for payment",
        criteria=[
            "Contains an invoice number",
            "Shows an amount due",
        ],
    ),
    ClassifyClass(
        id="purchase_order",
        label="Purchase order",
        description="Buyer-issued request for goods or services",
        criteria=[
            "Contains a purchase order number",
            "Issued by the buyer rather than the supplier",
        ],
    ),
    ClassifyClass(
        id="receipt",
        label="Receipt",
        description="Evidence that payment was completed",
    ),
]

Class IDs must be unique. Keep IDs stable when display labels or descriptions change because result labels join back to the request by class_id.

Subclasses

Use subclasses when a broad class has meaningful variants:

from ndi_sdk.models.document_ops import ClassifyClass, ClassifySubclass

classes = [
    ClassifyClass(
        id="agreement",
        label="Agreement",
        description="A signed legal agreement",
        subclasses=[
            ClassifySubclass(
                id="msa",
                label="Master services agreement",
                description="Governs an ongoing service relationship",
            ),
            ClassifySubclass(
                id="sow",
                label="Statement of work",
                description="Defines one project's scope and fees",
            ),
        ],
    )
]

Document or page classification

The default document granularity returns one unit for the entire source:

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import ClassifyClass

with NdiClient() as client:
    document = client.documents.create_upload("invoice.pdf")
    queued = client.documents.classify(
        document,
        classes=[
            ClassifyClass(
                id="invoice",
                label="Invoice",
                description="A supplier invoice",
            )
        ],
        granularity="document",
    )
    # Returns: Job with one classification unit

Use page when a file contains different content on different pages:

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import ClassifyClass

with NdiClient() as client:
    document = client.documents.create_upload("mailroom-scan.pdf")
    job = client.jobs.wait(
        client.documents.classify(
            document,
            classes=[
                ClassifyClass(
                    id="invoice",
                    label="Invoice",
                    description="A supplier invoice",
                ),
                ClassifyClass(
                    id="receipt",
                    label="Receipt",
                    description="Proof of payment",
                ),
                ClassifyClass(
                    id="contract",
                    label="Contract",
                    description="A signed agreement",
                ),
            ],
            granularity="page",
            wait_seconds=30,
        ).job_id
    )
    # Returns: ClassifyResult with one unit per selected page

    for unit in job.result.units:
        print(unit.page_range, unit.labels[0].class_id)

Select pages

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import ClassifyClass, PageRange

with NdiClient() as client:
    document = client.documents.create_upload("mailroom-scan.pdf")
    queued = client.documents.classify(
        document,
        classes=[
            ClassifyClass(
                id="invoice",
                label="Invoice",
                description="A supplier invoice",
            )
        ],
        granularity="page",
        page_ranges=[PageRange(start=3, end=12)],
        parse_mode="medium",
    )
    # Returns: Job for pages 3 through 12

Handle unknown content

Value	Behavior
`allow`	A unit can return `unknown=True` when none of the requested classes fits
`force_best`	Every unit is assigned the highest-ranked requested class

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import ClassifyClass

with NdiClient() as client:
    document = client.documents.create_upload("mailroom-scan.pdf")
    queued = client.documents.classify(
        document,
        classes=[
            ClassifyClass(
                id="invoice",
                label="Invoice",
                description="A supplier invoice",
            )
        ],
        unknown_policy="allow",
    )
    # Returns: Job; unrelated content can remain unknown

Start with allow when the set of possible documents is open-ended. Use force_best only when every input must belong to your closed class set.

Configure alternatives and reasons

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import (
    ClassifyClass,
    ClassifyOutputOptions,
)

with NdiClient() as client:
    document = client.documents.create_upload("mailroom-scan.pdf")
    queued = client.documents.classify(
        document,
        classes=[
            ClassifyClass(
                id="invoice",
                label="Invoice",
                description="A supplier invoice",
            )
        ],
        output=ClassifyOutputOptions(
            max_alternatives=5,
            include_reason=True,
        ),
    )
    # Returns: Job with up to five ranked labels per unit

max_alternatives defaults to 3, accepts 1–10, and includes the winner. Reasons are included by default.

Response structure

# After client.jobs.wait returns a succeeded classify job:
result = ...

for unit in result.units:
    print(unit.granularity)
    print(unit.page_range)
    print(unit.unknown)

    for label in unit.labels:
        print(label.class_id)
        print(label.subclass_id)
        print(label.label)
        print(label.rank)
        print(label.reason)
        print(label.confidence)

Labels are sorted best-first. rank=1 is the assigned class, or the top candidate when unknown=True. The reserved other ID can appear when no requested class matches. confidence is DREX’s probability for the label, averaged over the menu orders, when DREX decided it. When any other label in the unit lacks one, every such label is the share of pages or sheets assigned that class. Runner-up labels on an abstained unit keep DREX’s probability for that option.

Async classify

import asyncio

from ndi_sdk import AsyncNdiClient
from ndi_sdk.models.document_ops import ClassifyClass


async def main() -> None:
    async with AsyncNdiClient() as client:
        document = await client.documents.create_upload("invoice.pdf")
        queued = await client.documents.classify(
            document,
            classes=[
                ClassifyClass(
                    id="invoice",
                    label="Invoice",
                    description="A supplier invoice",
                )
            ],
            wait_seconds=30,
        )
        job = await client.jobs.wait(queued.job_id, timeout=600)
        # Returns: succeeded Job with a ClassifyResult
        print(job.result.units)


asyncio.run(main())

Complete example

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import (
    ClassifyClass,
    ClassifyOutputOptions,
)

classes = [
    ClassifyClass(
        id="invoice",
        label="Invoice",
        description="Supplier request for payment",
    ),
    ClassifyClass(
        id="purchase_order",
        label="Purchase order",
        description="Buyer-issued order for goods or services",
    ),
    ClassifyClass(
        id="receipt",
        label="Receipt",
        description="Evidence of completed payment",
    ),
    ClassifyClass(
        id="contract",
        label="Contract",
        description="Agreement signed by two or more parties",
    ),
]

with NdiClient() as client:
    document = client.documents.create_upload("mailroom-scan.pdf")
    queued = client.documents.classify(
        document,
        classes=classes,
        granularity="page",
        unknown_policy="allow",
        output=ClassifyOutputOptions(
            max_alternatives=3,
            include_reason=True,
        ),
        wait_seconds=30,
    )
    job = client.jobs.wait(queued.job_id, timeout=600)
    # Returns: ClassifyResult with ranked labels for every page

    for unit in job.result.units:
        if unit.unknown:
            print(unit.page_range, "Unknown")
        else:
            winner = unit.labels[0]
            print(unit.page_range, winner.class_id, winner.reason)

Error handling

from ndi_sdk import InvalidRequestError, JobFailedError, NdiClient
from ndi_sdk.models.document_ops import ClassifyClass

with NdiClient() as client:
    try:
        queued = client.documents.classify(
            client.documents.create_upload("document.pdf"),
            classes=[
                ClassifyClass(
                    id="invoice",
                    label="Invoice",
                    description="A supplier invoice",
                )
            ],
        )
        job = client.jobs.wait(queued.job_id, timeout=600)
        # Returns: succeeded Job, or raises for request/job failure
    except InvalidRequestError as exc:
        print(exc.code, exc.message)
    except JobFailedError as exc:
        print(exc.job.status, exc.job.error)

Common failures include empty or duplicate class IDs, reserved IDs, invalid page ranges, unsupported file types, and a parse-result source.

Best practices

Separate nearby classes

Explain how similar classes differ rather than repeating their labels.

Keep IDs stable

Treat class_id as the durable join key and labels as display text.

Allow unknowns first

Avoid forcing unrelated documents into a class while developing the taxonomy.

Use page mode deliberately

Page granularity is for mixed packets; document granularity is simpler for one logical file.

Get started

Core methods

Async and utilities

Basic usage

Method signature

Parameters

Returns

Define classes

Subclasses

Document or page classification

Select pages

Handle unknown content

Configure alternatives and reasons

Response structure

Async classify

Complete example

Error handling

Best practices

Separate nearby classes

Keep IDs stable

Allow unknowns first

Use page mode deliberately

Next steps

​Basic usage

​Method signature

​Parameters

​Returns

​Define classes

​Subclasses

​Document or page classification

​Select pages

​Handle unknown content

​Configure alternatives and reasons

​Response structure

​Async classify

​Complete example

​Error handling

​Best practices

Separate nearby classes

Keep IDs stable

Allow unknowns first

Use page mode deliberately

​Next steps

Basic usage

Method signature

Parameters

Returns

Define classes

Subclasses

Document or page classification

Select pages

Handle unknown content

Configure alternatives and reasons

Response structure

Async classify

Complete example

Error handling

Best practices

Next steps