Split

documents.split finds logical documents inside one file. PDFs and other page-based sources become ordered page-range segments. Workbooks become one segment per worksheet, classified against the classes you provide.

Basic usage

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import SplitCategory

with NdiClient() as client:
    packet = client.documents.create_upload("vendor-packet.pdf")
    queued = client.documents.split(
        packet,
        classes=[
            SplitCategory(
                id="invoice",
                label="Invoice",
                description="A supplier invoice",
            ),
            SplitCategory(
                id="receipt",
                label="Receipt",
                description="Proof of payment",
            ),
        ],
        wait_seconds=30,
    )
    job = client.jobs.wait(queued.job_id, timeout=600)
    # Returns: succeeded Job; job.result is a SplitResult

    for segment in job.result.segments:
        print(segment.split_class, segment.start_page, segment.end_page)

Method signature

def split(
    source: DocumentSource | UploadResponse,
    *,
    classes: list[SplitCategory],
    unknown_policy: Literal["include", "force", "error"] = "include",
    page_ranges: list[PageRange] | None = None,
    parse_mode: Literal["low", "medium", "high"] = "low",
    overlap_policy: Literal["exclusive", "shared_boundary_page"] = "exclusive",
    quality: OperationQuality = "auto",
    split_rules: str | None = None,
    output: SplitOutputOptions | None = None,
    wait_seconds: int = 0,
    idempotency_key: str | None = None,
) -> Job

Parameters

Parameter	Type	Required	Description
`source`	`DocumentSource` or `UploadResponse`	Yes	Packet, workbook, URL, workspace file, or successful parse job
`classes`	`list[SplitCategory]`	Yes	Document or worksheet classes to identify
`unknown_policy`	`"include"` / `"force"` / `"error"`	No	Keep unmatched content, force its best class, or fail
`page_ranges`	`list[PageRange]`	No	One-based inclusive page ranges. Unsupported for spreadsheets
`parse_mode`	`"low"` / `"medium"` / `"high"`	No	Processing effort before splitting
`overlap_policy`	`"exclusive"` / `"shared_boundary_page"`	No	Keep segments disjoint, or include a boundary page in both adjacent segments
`quality`	`"auto"`	No	Only accepted value
`split_rules`	`str`	No	Additional natural-language rules for finding boundaries
`output`	`SplitOutputOptions`	No	Include segment markdown or materialize segment files
`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

Returns

A Job. After success, job.result is a SplitResult:

Field	Description
`file_name`	Name of the source
`lane`	Processing lane
`page_count`	Number of source pages or logical spreadsheet pages
`segments`	Ordered classified and unclassified cuts
`units`	Billable units

Define classes

Each class needs a stable id, display label, and a description that distinguishes it from nearby classes:

from ndi_sdk.models.document_ops import SplitCategory

classes = [
    SplitCategory(
        id="purchase_order",
        label="Purchase order",
        description="Buyer-issued order listing requested goods or services",
    ),
    SplitCategory(
        id="invoice",
        label="Invoice",
        description="Supplier request for payment with an invoice number",
    ),
    SplitCategory(
        id="receipt",
        label="Receipt",
        description="Evidence that a payment was completed",
    ),
    SplitCategory(
        id="bank_statement",
        label="Bank statement",
        description="Periodic account activity issued by a bank",
    ),
]

Avoid labels whose descriptions overlap completely. The id is what appears in result joins; keep it stable if you revise display text.

Subclasses and instance keys

Add subclasses for finer segment labels and an instance key when each segment should carry a document identifier:

from ndi_sdk.models.document_ops import (
    SplitCategory,
    SplitInstanceKey,
    SplitSubclass,
)

invoice = SplitCategory(
    id="invoice",
    label="Invoice",
    description="A supplier request for payment",
    subclasses=[
        SplitSubclass(
            id="utility",
            label="Utility invoice",
            description="Invoice for electricity, gas, water, or telecom",
        ),
        SplitSubclass(
            id="goods",
            label="Goods invoice",
            description="Invoice for purchased physical goods",
        ),
    ],
    instance_key=SplitInstanceKey(
        name="invoice_number",
        description="Supplier invoice identifier",
    ),
)

The selected subclass is returned with the segment classification. segment.instance carries the requested key and extracted value when one is available.

Control unmatched content

unknown_policy determines what happens when content matches none of the classes:

Value	Behavior
`include`	Keep an unclassified segment. This is the default
`force`	Assign the closest requested class
`error`	Fail instead of returning unmatched content

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import SplitCategory

with NdiClient() as client:
    packet = client.documents.create_upload("packet.pdf")
    queued = client.documents.split(
        packet,
        classes=[
            SplitCategory(
                id="invoice",
                label="Invoice",
                description="A supplier invoice",
            )
        ],
        unknown_policy="include",
    )
    # Returns: Job; unmatched pages remain as unclassified segments

Use include when completeness matters. Use force only when every page must belong to one of a closed set of classes.

Page selection and parse mode

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

with NdiClient() as client:
    packet = client.documents.create_upload("packet.pdf")
    queued = client.documents.split(
        packet,
        classes=[
            SplitCategory(
                id="statement",
                label="Statement",
                description="Periodic financial statement",
            )
        ],
        page_ranges=[PageRange(start=3, end=40)],
        parse_mode="medium",
    )
    # Returns: Job covering pages 3 through 40

Page ranges are not supported for spreadsheet sources. Use medium or high only when the default parse is not sufficient; higher modes add latency.

Split rules

Use split_rules for a boundary convention the class descriptions do not express:

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import SplitCategory

with NdiClient() as client:
    packet = client.documents.create_upload("packet.pdf")
    queued = client.documents.split(
        packet,
        classes=[
            SplitCategory(
                id="invoice",
                label="Invoice",
                description="A supplier invoice",
            )
        ],
        split_rules=(
            "Start a new invoice when the invoice number changes. "
            "Attach continuation pages to the preceding invoice."
        ),
    )
    # Returns: Job using the additional boundary guidance

Use overlap_policy="shared_boundary_page" when the page at a detected boundary belongs to both neighboring documents. The default exclusive policy keeps every source page in only one segment.

Include content or files

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import SplitCategory, SplitOutputOptions

with NdiClient() as client:
    packet = client.documents.create_upload("packet.pdf")
    job = client.jobs.wait(
        client.documents.split(
            packet,
            classes=[
                SplitCategory(
                    id="invoice",
                    label="Invoice",
                    description="A supplier invoice",
                )
            ],
            output=SplitOutputOptions(
                include_content=True,
                materialize_files=True,
            ),
            wait_seconds=30,
        ).job_id
    )
    # Returns: SplitResult with segment markdown and downloadable artifacts

    for segment in job.result.segments:
        print(segment.content)
        for artifact in segment.artifacts:
            print(artifact.url)

Document segments are materialized only when requested. Spreadsheet segments always include a single-sheet .xlsx artifact.

Response structure

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

for segment in result.segments:
    print(segment.sequence)
    print(segment.status)                    # matched or unclassified
    print(segment.split_class)               # winning class, or None
    print(segment.split_classes)             # class hierarchy, when returned
    print(segment.start_page, segment.end_page)
    print(segment.sheet_name)                # spreadsheet sources
    print(segment.instance)                  # requested per-segment identifier
    print(segment.classification_confidence)
    print(segment.boundary_confidence)
    print(segment.content)
    print(segment.artifacts)
    print(segment.warnings)

Page-based segments use start_page and end_page. Spreadsheet segments use sheet_name; their page values correspond to the worksheet’s one-based position. JSON sources may use json_pointer. classification_confidence and boundary_confidence contain a readable band and an optional score. unavailable means no score was produced, not zero confidence.

Reuse a parse

from ndi_sdk import NdiClient, ParseResultSource
from ndi_sdk.models.document_ops import SplitCategory

with NdiClient() as client:
    upload = client.documents.create_upload("packet.pdf")
    parsed = client.jobs.wait(
        client.documents.parse(upload, wait_seconds=30).job_id
    )
    queued = client.documents.split(
        ParseResultSource(job_id=parsed.job_id),
        classes=[
            SplitCategory(
                id="invoice",
                label="Invoice",
                description="A supplier invoice",
            )
        ],
    )
    # Returns: Job; NDI reuses the successful ParseResult

Async split

import asyncio

from ndi_sdk import AsyncNdiClient
from ndi_sdk.models.document_ops import SplitCategory


async def main() -> None:
    async with AsyncNdiClient() as client:
        packet = await client.documents.create_upload("packet.pdf")
        queued = await client.documents.split(
            packet,
            classes=[
                SplitCategory(
                    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 SplitResult
        print(len(job.result.segments))


asyncio.run(main())

Complete example

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import SplitCategory, SplitOutputOptions

classes = [
    SplitCategory(
        id="purchase_order",
        label="Purchase order",
        description="Buyer-issued order",
    ),
    SplitCategory(
        id="invoice",
        label="Invoice",
        description="Supplier request for payment",
    ),
    SplitCategory(
        id="receipt",
        label="Receipt",
        description="Evidence of completed payment",
    ),
    SplitCategory(
        id="bank_statement",
        label="Bank statement",
        description="Periodic account activity from a bank",
    ),
]

with NdiClient() as client:
    packet = client.documents.create_upload("vendor-packet.pdf")
    queued = client.documents.split(
        packet,
        classes=classes,
        unknown_policy="include",
        split_rules="Start a new segment when the document identifier changes.",
        output=SplitOutputOptions(include_content=True),
        wait_seconds=30,
    )
    job = client.jobs.wait(queued.job_id, timeout=600)
    # Returns: SplitResult with ordered cuts and inline content

    print(f"Found {len(job.result.segments)} segments")
    for segment in job.result.segments:
        label = (
            segment.split_class.label
            if segment.split_class is not None
            else "Unclassified"
        )
        print(label, segment.start_page, segment.end_page)

Error handling

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

with NdiClient() as client:
    try:
        queued = client.documents.split(
            client.documents.create_upload("packet.pdf"),
            classes=[
                SplitCategory(
                    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 invalid classes, unsupported file types, spreadsheet page ranges, and unknown_policy="error" when content is unclassified.

Best practices

Define distinct classes

Give each class a stable ID and a description that separates it from adjacent classes.

Keep unknowns visible

Start with unknown_policy="include" so unexpected packet content is not silently forced.

Add rules for boundaries

Use split_rules for continuation pages or identifier changes, not to replace class descriptions.

Materialize only when needed

Request files when downstream systems need individual documents; use inline content for inspection.

Get started

Core methods

Async and utilities

Basic usage

Method signature

Parameters

Returns

Define classes

Subclasses and instance keys

Control unmatched content

Page selection and parse mode

Split rules

Include content or files

Response structure

Reuse a parse

Async split

Complete example

Error handling

Best practices

Define distinct classes

Keep unknowns visible

Add rules for boundaries

Materialize only when needed

Next steps

​Basic usage

​Method signature

​Parameters

​Returns

​Define classes

​Subclasses and instance keys

​Control unmatched content

​Page selection and parse mode

​Split rules

​Include content or files

​Response structure

​Reuse a parse

​Async split

​Complete example

​Error handling

​Best practices

Define distinct classes

Keep unknowns visible

Add rules for boundaries

Materialize only when needed

​Next steps

Basic usage

Method signature

Parameters

Returns

Define classes

Subclasses and instance keys

Control unmatched content

Page selection and parse mode

Split rules

Include content or files

Response structure

Reuse a parse

Async split

Complete example

Error handling

Best practices

Next steps