--- name: llamaparse-classify-and-split-documents description: Sort a batch of mixed documents by type and split concatenated or multi-document files into their individual parts, reviewing low-confidence results before anything is acted on. Use when the user has a folder or set of mixed files to sort by type, asks which files are invoices or contracts, has a scanned bundle or PDF that holds several documents, or wants one file broken into its parts. --- # Classify and split documents Two different questions are in play, and mixing them up causes most errors here. **Classify** asks "what kind of document is this whole file?" **Split** asks "where does one document end and the next begin inside this file?" A bundle of three invoices is one file that needs splitting, then three classifications. Run them in that order, and never classify a file that you already know is a concatenation, because the single label will be wrong for most of its pages. ## 1. Confirm the project and the file set Call `getUserProjects` first and confirm which project the work belongs to. Then list what you are working with using `listDirectory` or `listDirectories`. Count the files and note their types (PDF, image, spreadsheet, scan). Page through long listings rather than loading everything at once; a directory of 800 files should be handled in pages, with a running count of what has been processed. Estimate the work before starting with `estimateFileComplexity` on a few representative files. Scanned, image-heavy or very long files take longer and cost more, so tell the user the rough scope before you run anything large. ## 2. Triage: find the bundles before you classify Scan the file set for files that are likely to hold more than one document: unusually high page counts, filenames such as "batch", "scan_all", "combined", or merged PDFs. Check a sample with `estimateFileComplexity` or `readFileFromIndex` if a file is already indexed. Do not classify these until they are split. A single "invoice" label on a file that contains an invoice, a delivery note and a signed contract will hide two-thirds of its content. ## 3. Split concatenated files Use `splitFile` on the bundles from step 2. Splitting produces sections with boundaries and labels. Inspect the boundaries before trusting them: - **Boundaries at every page** usually means the splitter found no document breaks. Either the file really is one long document, or the rules are too fine. Check two or three pages by eye before accepting it. - **Very uneven section lengths** are a signal to check. A two-page section sitting between two forty-page sections is often a cover sheet or a stray page that belongs to a neighbour. - **Pages with no content** (blank, or a scan with only a stamp) should be flagged, not silently attached to a section. Keep the mapping from each output section back to its source file and page range. Every split result must be traceable to the original, or the user cannot check it later. ## 4. Classify each part Run `classifyFile` on each whole file (unsplit) and on each section from step 3. Record the document type and the confidence score that comes back. Do not write the label into a report until you have read the confidence. Work out the review queue using these bands, and state the band thresholds in your report so the user can change them: | Confidence | Action | |---|---| | High (clearly above your threshold, and the top two labels are far apart) | Accept the label | | Medium (close second label, or the document is short) | Review a sample of the pages | | Low (below threshold, or the label conflicts with the filename) | Put in the review queue, do not act on it | A close second label is more important than the top score alone. A file scored 0.61 "invoice" and 0.58 "receipt" is a coin toss, not a classification. ## 5. Use the cross-checks Before reporting, look for disagreement between signals: - The filename says "contract" and the classifier says "invoice". - A section classified as one type is much shorter or longer than typical for that type. - A file's classification changes between the whole-file pass and the section pass. This usually means the split was wrong or the file mixes types. Each disagreement goes in the review queue, with the evidence, not into a confident label. ## Common patterns and traps - **Classifying bundles whole.** The most common error. Always split first, then classify. - **Trusting high scores on very short files.** A two-page file can score high on a type it only weakly resembles. Read the first page yourself. - **Scans with poor OCR.** Low-quality scans produce low-confidence labels that look like a document-type problem. Check parse quality before assuming the document is ambiguous. - **Splitting on the wrong boundary.** A repeated letterhead or page header can look like a new document. If every split falls on the same header, that is the cause. - **Losing the mapping.** Renaming or moving split files without recording where each came from makes the result unauditable. Keep the source-to-section map in the output. - **Assuming one label per file.** Some files are legitimately mixed, such as an invoice with an attached terms page. Report "mixed" with the parts rather than forcing one label. ## Output ``` Scope: Split: → (boundary method, any uneven sections flagged) Classified (accepted, high confidence): — Review queue (low or medium confidence): - : top "