Classify

Category: Processing

The Classify activity assigns a document class (type) to each document, so the right extraction schema and business rules apply. Classification uses the document's OCR text, its page images, or both.

Configuration

Defaults below are what a new project starts with.

Document Classes and Guidelines belong to the project: every Classify step reads them, and the panel says so when the workflow has several. A step can offer only some of the classes, or send its own description of a class or its own guidelines, shown as Custom in this step with Reset to project text. Every other setting belongs to this step alone, so two Classify steps can use different models or thresholds.

Setting	Description	Default
Enable Classification	Run the step at all. Off leaves documents unclassified.	On
Document Classes	The list of document types to classify into.	(none)
Guidelines	Additional classification instructions for the model.	(empty)
Confidence Threshold	Classifications below this confidence are flagged for review.	0.7
Auto-generate Classes	Let the model propose new document classes it discovers.	On
Include Reasoning	Ask the model to explain each classification.	On
Send Images	Send page images to the model.	Off
Send Text	Send OCR text to the model.	On
Send Images of Pages Without Text	When only text is sent, still send the image of a page that has no text (a blank page, a photo). Not available for text-only models; with one, the images are not sent.	On
Max Image Pages	How many page images to send, when images are sent.	3
Max Text Pages	How many pages of OCR text to send.	3

A new project therefore starts in discovery mode: it has no classes yet, and the model is asked to propose a document type for whatever arrives. The step reads text only, over the first 3 pages, because the document type is almost always decided by the opening pages and text alone keeps the call cheap. Once you have settled on a class list, turn Auto-generate Classes off so the model chooses from your classes instead of inventing new ones.

While Auto-generate Classes is on, the step classifies a transaction's documents one at a time, so each one sees the classes the documents before it proposed. Two documents of a new type then share one class instead of each inventing a name for it. Turning the setting off brings back parallel classification.

How the model decides

The classification call gives the model three things, and nothing else:

1. What it can look at - the document's page images, its OCR text, or both, depending on Send Images and Send Text.
2. The list of document classes, each as its name plus its description. The description is the model's only instruction about what belongs in that class, so it does the heavy lifting. Write it the way you would explain the class to a new colleague, and say what distinguishes it from the neighbouring class rather than just restating the name.
3. The classification guidelines, passed through verbatim. Use them for rules that span classes and so belong to no single description: "if it shows both an invoice number and a payment reference, it is a remittance advice, not an invoice".

The model returns the class it picked, a confidence score from 0 to 1, alternative classes it also considered, and, when Include Reasoning is on, an explanation of why it chose that class. A classification whose confidence falls below the activity's confidence threshold is flagged for review instead of being accepted silently.

So when classification is wrong, sharpening the class descriptions is the first thing to try, and the guidelines are the second. Both are cheaper and more robust than a classification rule, which encodes a fixed promise about the data.

Pages and documents without text

A page with no text is a normal page: a blank page, a photo of a person, a signature sheet. OCR reads it and finds nothing, and that is not an error.

• Some pages of a document have text: classification works as usual. Each page without text is marked to the model as "(no text on this page)".
• No page has text, and page images are sent (Send Images on, or Send Images of Pages Without Text on): the model classifies from the images.
• No page has text, and no image is sent: there is nothing for the model to read, so it is not called. The pre-classification rule still runs first and can assign a class (from the file name, for example). Otherwise the document is classified as Unknown with confidence 0, which flags it for review, and then the post-classification rule runs and can still assign a class. The Activity Log says "LLM not called: no text on any page, and page images are not sent". This happens even with Auto-generate Classes on: with nothing to read, there is nothing to name.

Max Text Pages limits which pages are read. If the first pages are all blank and the text starts later, raise the limit, or turn on Send Images of Pages Without Text.

A page that never went through OCR is different. If the step sends text and a page has no OCR result at all (there is no OCR step before Classify, or OCR is off in it), the step fails at once and says which pages, instead of classifying from the rest. Add an OCR step, or send page images.

Re-running a single document from the transaction viewer follows the same rules.

Unknown: the built-in fallback class

When the model classifies against a fixed class list, Unknown is always one of its options. You do not need to create it, and adding it to your class list yourself gains nothing.

Whenever your project has document classes and Auto-generate Classes is off, an Unknown class is added to the list the model sees, described as "use when the document does not clearly match any of the other predefined types". It gives the model a way to say "none of these" instead of forcing a wrong answer out of a document that genuinely does not belong to any of your classes.

What follows from a document being classified as Unknown:

• Extraction is skipped entirely for it. Unknown has no class-specific fields, so there is nothing to extract, and the document is marked with a note saying so.
• Class-specific fields cannot be added to it in the Transaction Viewer. Assign it a real class first, or add the field as a general field.
• A reviewer can change the document's type by hand, which brings that class's fields with it.

Treat a run with many Unknown documents as a signal: either a class is missing from your list, or the descriptions do not cover the variants that arrive in practice.

Two exceptions are worth knowing:

• With Auto-generate Classes on, which is how a new project starts, Unknown is not offered at all. The model is asked to propose a specific new document type instead, because "invent a name for it" and "give up" are contradictory instructions. Unknown becomes available once you turn auto-generate off and classify against a fixed class list.
• If you do define your own class named Unknown, it is used as a real class of yours, with your description and your fields, and nothing is injected.

Giving every document the same class

Turning Enable Classification off leaves documents unclassified, which also means no class-specific extraction fields and no class-scoped business rules apply to them.

When the answer is known in advance rather than decided per document (the project handles a single document type, or a feed only ever delivers one type) keep classification on and add a pre-classification rule with a single condition using the Always (any document) target and that one class. Every document is then classified as that class, and the model is never called, so there is no AI cost. See Always below.

Classification rules

Two optional rules run around the model call, configured in the Classify activity's Classification Rules panel.

Pre-classification rule runs first, before the model is called. Each condition tests the source file name, the document text, a transaction metadata value, or an extracted field, or uses the Always (any document) target, which matches everything. It then resolves to one or more classes:

• One class: the document is classified straight away and the model is never called. Useful when the file name alone settles the question.
• Several classes: the document still goes to the model, but the model may only choose among those classes (plus Unknown, if your project defines it). Use this when a signal narrows the answer without settling it, for example a file name prefix that proves the document belongs to the invoice family but not which member of it.

When a condition names several classes, the builder shows an LLM decides badge on that condition, and the confidence input disappears because the model supplies its own confidence.

Post-classification rule runs after the model and can override the result. It can read the class the model picked, its confidence, and the candidate classes the pre-rule narrowed it to, so it can apply a fallback when the model was not confident within the range.

Conditions are evaluated top to bottom and the first match wins. If nothing matches, the model classifies against the full class list.

The Regex match type takes a JavaScript regular expression. Matching is case-insensitive and the pattern may match anywhere in the text, so leave out ^, $ and the inline flag (?i), which JavaScript rejects. The builder checks the pattern as you type and shows the compile error under it; Regex help opens a short reference and Build with AI writes the pattern from a description. See Regular Expressions for the full introduction.

When a rule fails

A rule is one function: a pattern that does not compile or a line that throws stops every condition in it, including the ones above the error that would have matched. That is a failed step, not a silent fall-through to the model. The transaction takes the activity's Failed exit if one is wired (Handling failures), and otherwise fails, and the Activity Log records the rule (pre or post), the document, and the error text. A rule that cannot run never hands its documents to the model, because a document the rule should have classified without an AI call would otherwise get an AI answer that nothing in the transaction explains.

Two things prevent this at authoring time: the builder withholds a rule with an invalid regex until it is fixed, and the assistant refuses to save one.

Reading the Activity Log

Each document the step processes leaves a classified as row in the transaction's Activity Log, so you can see how the class was decided rather than only that the step ran:

• whether the pre-classification rule was configured, matched nothing, assigned the class, or narrowed the model to a candidate set
• whether the model was called, and with what answer and confidence
• whether the post-classification rule matched nothing or overrode the answer

Use it to confirm that a file-name rule really skipped the model, or to see which stage produced a class you did not expect. Very large transactions record the first 100 documents and count the rest in one line.

Always

The Always (any document) target has no comparison to fill in: the condition fires for every document. Two ways to use it:

• As the only condition, to assign one class (or narrow to one candidate set) for everything the step sees, while keeping classification on for the rules and the review threshold.
• As the last condition, as a catch-all: the specific conditions above it handle what they recognise, and everything else falls into a default class instead of going to the model.

Because the first match wins, any condition placed below an Always condition never runs. The builder marks those conditions so they are easy to spot.

Notes

• A document already classified upstream (for example by a Transform set_document_class call) keeps its class; Classify skips it.