Classify a document

Classify reads the original file. It rejects a parse_result source.

Python
TypeScript
curl

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

with NdiClient() as client:
    document = client.documents.create_upload("invoice.pdf")
    job = client.jobs.wait(
        client.documents.classify(
            document,
            classes=[
                ClassifyClass(id="invoice", label="Invoice", description="A supplier invoice"),
            ],
            wait_seconds=30,
        ).job_id
    )
    for unit in job.result.units:
        print(unit.unknown, unit.labels)

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const document = await client.documents.createUpload("invoice.pdf");
const job = await client.jobs.wait(
  (
    await client.documents.classify(document, {
      classes: [{ id: "invoice", label: "Invoice", description: "A supplier invoice" }],
      wait_seconds: 30,
    })
  ).job_id,
);
console.log(job.result);

UPLOAD_ID=$(curl -s -X POST "$NDI_BASE_URL/v1/uploads" \
  -H "X-API-Key: $NDI_API_KEY" \
  -F "file=@invoice.pdf" | jq -r '.upload_id')

curl -s -X POST "$NDI_BASE_URL/v1/classify?wait_seconds=60" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\":{\"type\":\"upload\",\"upload_id\":\"$UPLOAD_ID\"},\"classes\":[{\"id\":\"invoice\",\"label\":\"Invoice\",\"description\":\"A supplier invoice\"}]}"

Options

Option	Default	Meaning
`classes`	you must set this	Caller-defined labels. Each class needs a stable `id`, a `label`, and a `description` the model can use
`granularity`	`document`	Score the whole file once, or return one unit per selected page
`page_ranges`	all pages	One-based inclusive ranges to parse and classify
`unknown_policy`	`allow`	`allow` may mark a unit `unknown`. `force_best` commits an ambiguous unit to one of your classes, but a page that is blank, unreadable, unparsed, or never read because of document size is still returned unknown, and so is an empty spreadsheet tab. Unread pages are disclosed as `classification_unread_pages`
`output.max_alternatives`	`3`	How many ranked labels to keep per unit, including the winner
`output.include_reason`	`true`	When true, each label may include a short reason string

Result

result.units is one row per document, or per page when granularity is page.

Field	Meaning
`unknown`	True when no requested class won this unit — including reserved `other` and pages never read by any model — regardless of `unknown_policy`. False when a requested class won, even if some pages were `other`
`pages_read_fraction`	Fraction of expected pages that entered at least one model prompt, from 0 to 1. `1.0` when every page was read; otherwise `1 − unread/expected`
`labels`	Classes for this unit, already sorted best-first. `rank` is the 1-based position in that list: `1` is the assigned class (or the top class when `unknown` is true). Later ranks are runners-up, limited by `output.max_alternatives`. `rank` is not the confidence score
`labels[].class_id`	Id of this label. One of the request `classes`, or the reserved id `other` when no requested class matched this slice. `other` can be the top label when `unknown` is true, or a ranked alternative when some pages did not match. Join request classes on this only when the id is in your `classes` list
`labels[].label`	Display name of that class. Copied from the request for a caller-defined `class_id`; a freeform name when `class_id` is `other`
`labels[].reason`	Short model explanation of why this class was chosen, only when `output.include_reason` is true
`labels[].confidence`	DREX’s probability for this label, averaged over the menu orders, when DREX decided it. See below for the page-share fallback and for abstain runner-ups

When every label in the unit has a DREX probability, confidence is that probability. A document label shared by several segments is the page-weighted mean of the probability recorded on each segment. Labels are ordered by page coverage. Confidence is per label, so a lower rank can carry a higher confidence. An abstained unit’s top label is that mean. Its runner-up labels carry DREX’s probability for that runner-up option, not a page share. When any other label in the unit lacks a DREX probability, every such label uses the share of the unit’s read pages or sheets assigned that class. Pages that never entered a prompt are excluded from that share and disclosed as classification_unread_pages.

Getting started

Guides

Agents

Concepts

Troubleshooting

Options

Result

​Options

​Result

Options

Result