Perception
Split
client.documents.split(params, options?) cuts a packet into documents, each with a class. It takes the shared parameters and:
| Parameter | Type | Required | Description |
|---|---|---|---|
classes | Array<{ id, label, description?, subclasses?, instance_key? }> | Yes | The document classes to cut on. See classes. Split's own options are on Split. |
unknown_policy | "include" | "force" | "error" | No | "include" (default) keeps unmatched pages as unclassified, "force" gives them the best class, "error" fails the job. |
overlap_policy | "exclusive" | "shared_boundary_page" | No | "exclusive" (default) keeps segments apart; "shared_boundary_page" puts a boundary page in both neighbors. |
split_rules | string | No | Free-text guidance on how to cut the packet. |
output | { include_content?, materialize_files? } | No | What each segment holds. See output. |
page_ranges | Array<{ start, end }> | No | Pages to consider. Not for workbooks. Default: all pages. |
parse_mode | "low" | "medium" | "high" | No | How hard the parse behind the split works. Only low with a parse_result source. Default: "low". |
Each object option takes these keys:
classes
One entry per class, each an object:
| Key | Type | Default | Description |
|---|---|---|---|
classes[].id | string | Required | The class's id. |
classes[].label | string | Required | The class's name. |
classes[].description | string | "" | What belongs in the class. |
classes[].subclasses | Array<{ id, label, description? }> | None | Finer classes under this one, each with subclasses[].id and subclasses[].label (both required) and an optional subclasses[].description. |
classes[].instance_key | { name, description, required? } | None | A value that tells one document of the class from the next, such as an invoice number. |
classes[].instance_key.name | string | Required | The value's name. |
classes[].instance_key.description | string | Required | Where to find it. |
classes[].instance_key.required | boolean | false | Whether every document of the class has it. |
output
| Key | Type | Default | Description |
|---|---|---|---|
output.include_content | boolean | false | Put each segment's Markdown in content. |
output.materialize_files | boolean | false | Give each segment a downloadable file. |
const job = await client.documents.split({
source: { type: "url", url: "https://example.com/packet.pdf", file_name: "packet.pdf" },
classes: [
{ id: "invoice", label: "Invoice", description: "A supplier invoice" },
{ id: "receipt", label: "Receipt", description: "A payment receipt" },
],
});
const done = await client.jobs.wait(job.job_id);Class ids must be unique and can't contain /, and blank_page, unreadable_content and __ndi_unclassified are reserved. See Split.