> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Document classifiers
> Train or import deterministic machine-learning models that sort document pages into categories, and route each page in a workflow based on the predicted label.
export const release_0 = "5.11"
SaaS · {release_0}
**Available on SaaS with FlowX.AI {release_0}.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.
A Document Classifier is a trained machine-learning model that sorts document pages into categories you define, such as `INVOICE`, `NATIONAL_ID`, or `BANK_STATEMENT`, so a workflow can route each page to the right handling. Classification is deterministic: the same page always gets the same result, and no large language model runs at inference time.
Document Classifiers live in your project under **Integrations** → **Document Classifiers**, alongside Data Sources, Workflows, and Proxy Connections.
***
## When to use a Document Classifier
FlowX offers two ways to classify documents. Pick based on how well-defined your document types are and how much labeled data you have:
| Approach | Best for |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Document Classifier** (this page) | Narrow, well-defined document types at scale. Deterministic results, low latency, low cost per page. Needs labeled example pages to train. |
| **LLM-based classification** with a [Custom Agent](./custom-agent-node) | Standing something up fast without training data, or open-ended document types. Results vary between runs and cost more per page. |
Two other features have similar names but do different things: **Document Intelligence** ingests documents into a knowledge base for AI retrieval, and the **Extract Data from File** workflow node extracts field values from a document. A Document Classifier only answers one question per page: *which category is this?*
***
## Create a Document Classifier
In your project, go to **Integrations** → **Document Classifiers** and click **+**.
Enter a **Name** and an optional **Description**.
Leave **Use preexisting model bundle** toggled **OFF** to create an empty classifier and train it in FlowX (the usual path). Toggle it **ON** to import a model bundle exported from another FlowX environment. See [Import a pre-trained bundle](#import-a-pre-trained-bundle).
The classifier detail page has three tabs (**Classes**, **Data**, and **Trained Models**) that mirror the three parts of a classifier: a label taxonomy, a labeled page corpus, and trained model versions.
***
## Define classes
Classes are the categories the model sorts pages into. Open the **Classes** tab and click **New class**.
Must be UPPER\_SNAKE\_CASE (letters, digits, underscores, starting with a letter, such as `NATIONAL_ID`) and unique within the classifier.
Describe what differentiates this class from the others. The description guides automatic pre-labeling when you upload unlabeled documents.
Snippets of text likely to appear verbatim in a document of this class.
Snippets that look like this class but are not. They help the model separate near-misses.
Every classifier ships with a locked **UNKNOWN** class as the default catch-all. Pages that don't belong to any of your classes get labeled `UNKNOWN` instead of landing in a wrong category.
Define at least two classes besides `UNKNOWN`, and make them mutually exclusive. If two classes overlap heavily, merge them and let a downstream step tell them apart.
***
## Build the corpus
The unit of classification is a **page**, not a file. The **Data** tab is where labeled pages accumulate into the training corpus. There are two ways to add pages:
* **Upload unlabeled batch**: drop ZIP, PDF, or Word files. Source files can be up to 20 MB each. The pages are pre-labeled automatically and queued for your review; each page needs review before it joins the corpus.
* **Upload sorted by class**: drop files that are already sorted per class; the pages join the corpus directly, without review.
Added pages join the corpus with an automatic **80% train / 20% test** split, assigned per class when the page enters and never reshuffled, so test results stay comparable between training runs. Pages labeled `UNKNOWN` go entirely to the test pool. The corpus table shows every page with its class, split, and upload batch. You can remove pages, but not relabel them in place.
***
## Train a model
In the **Data** tab, select the training pages to use and click **Train model**. Training requires at least **10 training pages for every class**; the locked `UNKNOWN` class is exempt. A warning appears when the corpus is heavily imbalanced: when one class has far more pages than another, the model tends to over-predict the bigger one.
Training runs asynchronously. Each successful run produces an immutable **model version** in the **Trained Models** tab, with its accuracy metrics, per-class results, and a confusion matrix. You can compare any two versions to see what changed between training runs.
The **main** version is the one workflows use. The first trained version becomes main automatically; promote a different version when it performs better.
Training and promotion work on the draft (WIP) version of your project. Committing a project version freezes the classifier's corpus and training for that version. Editing a committed classifier continues on a new draft.
### What travels between environments
When you export or build a project, the classifier's **class taxonomy travels with it** as part of the versioned configuration. The **corpus and trained models do not travel**: the target environment receives the classes and trains against its own data.
***
## Import a pre-trained bundle
If you already have a model trained in another FlowX environment, toggle **Use preexisting model bundle** ON when creating the classifier and upload the exported bundle: a ZIP with the model metadata and binary. FlowX validates the bundle on upload and adds it as an uploaded candidate version:
* It must define at least two classes, named in UPPER\_SNAKE\_CASE, without duplicates.
* Its training metrics must be present and consistent with the declared class set.
* FlowX rejects a bundle that fails validation; nothing is created. A bundle that uploads but fails processing leaves the classifier in a **Failed** state with a **Retry** option.
Bundles are produced by FlowX. Export them from an environment where the model was trained: hand-assembled bundles fail validation or produce meaningless predictions, because the model's features are tied to how it was trained.
***
## Classify pages in a workflow
Consume the trained model with the **Document Classification** node from the workflow node palette. The node is a pure classifier: it labels pages and writes the result. Routing happens in a downstream condition node.
| Field | Description | Default |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| **Document Classifier** | The classifier whose main model version runs. A read-only **Classes** hint lists its labels so you can build the downstream condition. | N/A |
| **File Content** | An expression that resolves to an array of extracted page texts, one entry per page, such as `${extractedPages}`. | N/A |
| **Confidence Threshold** | Predictions below this probability get flagged `low_confidence`. | `0.7` |
| **Response Key** | The key the node writes the result JSON under. | `responseKey` |
| **Timeout** | Inference call timeout, in milliseconds. | `10000` |
The node classifies **text, not files**. Extract page text upstream, for example with the **Extract Data from File** node or your document processing flow, and pass the array of page texts to **File Content**.
### Output
The node classifies each page independently and writes one result object:
```json theme={"dark"}
{
"pages": [
{
"page": 1,
"predictedLabel": "NATIONAL_ID",
"predictedProbability": 0.92,
"low_confidence": false,
"classes": [
{ "label": "NATIONAL_ID", "probability": 0.92 },
{ "label": "PASSPORT", "probability": 0.05 }
],
"error": null
}
],
"confidenceThreshold": 0.7,
"error": null
}
```
* `predictedLabel` is the highest-probability class; `classes` lists all class probabilities in descending order.
* `low_confidence` is `true` when `predictedProbability` is below the configured threshold. A low-confidence prediction is still a **successful** result. Use the condition node to route those pages to human review instead of treating them as failures.
* A single page failing to classify populates that page's `error` and the node still succeeds; the other pages classify normally.
* Whole-node failures set the top-level `error` and route to the node's error output. The error codes:
| Code | Meaning |
| ----------------------- | ---------------------------------------------------------------- |
| `MODEL_NOT_FOUND` | The selected classifier or its main model version doesn't exist. |
| `MODEL_NOT_READY` | The classifier has no trained, ready model version yet. |
| `NO_DOCUMENT_TEXT` | The File Content expression resolved to nothing. |
| `EMPTY_INPUT` | The input resolved to an empty page list. |
| `INVALID_TIMEOUT` | The configured timeout value isn't usable. |
| `INFERENCE_UNAVAILABLE` | The classification service is unreachable. Retryable. |
### Route by label
Add a **Condition** node after the Document Classification node and branch on the result: typically iterating `pages` and switching on `predictedLabel`, with a separate branch for `low_confidence` pages.
***
## Related resources
Build workflows that combine classifiers with REST calls, data operations, and AI nodes
LLM-based alternative for classification without training data
## Related topics
- [FlowX.AI 5.11.0 Release Notes](/release-notes/v5.x/v5.11.0-august-2026/v5.11.0-august-2026.md)
- [Deployment guidelines v5.11](/release-notes/v5.x/v5.11.0-august-2026/deployment-guidelines-v5.11.md)
- [Fan-out extraction](/5.9/ai-platform/patterns/fan-out-extraction.md)
- [Intent classification and routing](/5.9/ai-platform/patterns/intent-classification-routing.md)
- [Mortgage advisor chatbot](/5.9/ai-platform/tutorials/mortgage-advisor.md)