> ## 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.

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](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/custom-agent-node.md) | Standing something up fast without training data, or open-ended document types. Results vary between runs and cost more per page. |

> [!NOTE]
>
> 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

**1. Open Document Classifiers**

In your project, go to **Integrations** → **Document Classifiers** and click **+**.

**2. Name the classifier**

Enter a **Name** and an optional **Description**.

**3. Choose how the model gets trained**

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**.

**Class name** `string` *required*

Must be UPPER\_SNAKE\_CASE (letters, digits, underscores, starting with a letter, such as `NATIONAL_ID`) and unique within the classifier.

**Description** `string` *required*

Describe what differentiates this class from the others. The description guides automatic pre-labeling when you upload unlabeled documents.

**Positive examples** `list`

Snippets of text likely to appear verbatim in a document of this class.

**Negative examples** `list`

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.

> [!TIP]
>
> 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.&#x20;
* **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.&#x20;

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.

> [!NOTE]
>
> 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 with a project export or build**: the target environment receives the classes and trains against its own data.&#x20;

The corpus itself can now move between environments: export a classifier's corpus and import it into the classifier in the target environment. An imported corpus appears in a **read-only view** in the classifier's **Data** tab, so you can inspect the pages it was trained on without editing them there. Exporting a corpus requires the ML models permission. To move a trained model, use the pre-trained bundle flow described below.

## Manage trained versions at runtime

Each workspace keeps its own trained versions of a classifier, so a running environment can take a new version without a new build. Open the project, switch to the **Runtime** view, and select **Runtime Content** → **Document Classifiers**. The list shows each classifier's **Name**, **Defined in**, **Used by builds**, **Main version**, and **Status**. Open a classifier to see its **Trained Models**, **Data**, and **Classes** tabs.

### Promote a version to main

The **Trained Models** tab lists every version this environment holds for the classifier. One is **main**: the version served whenever a live workflow calls the classifier.

To change it, promote another version and confirm. Promotion takes effect immediately, on every build that runs the classifier, with no rebuild.

FlowX compares the version's classes with the classes your running builds branch on. If they don't line up, a warning lists:

* Classes the builds route on that the version can't produce: those branches never fire.
* Classes the version produces that no build handles: those pages take the default path.

Click **Promote anyway** to continue, or **Cancel**.

### Import a trained model or a corpus

* **Import trained model** uploads a trained version exported from another environment. It's added to the **Trained Models** list; promote it to serve it in workflows. If the version was already imported, or was exported from a different classifier, FlowX shows a warning first: click **Import anyway** to continue.
* **Import corpus** loads labelled pages from an exported corpus (a ZIP file up to 10 MB) into the **Data** tab. If the file uses classes the classifier doesn't have, map each one to an existing class or skip its pages: classes can't be added at runtime. If an import waits for your review, select **Finish import**.

***

## 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.

> [!WARNING]
>
> 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` |

> [!WARNING]
>
> 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

> [card] [Integration Designer](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/integration-designer.md)
>
> Build workflows that combine classifiers with REST calls, data operations, and AI nodes

> [card] [Custom Agent node](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/custom-agent-node.md)
>
> LLM-based alternative for classification without training data


## Related topics

- [Runtime content](https://docs.flowx.ai/6.x/docs/projects/runtime/runtime-content.md)
- [FlowX.AI Designer](https://docs.flowx.ai/6.x/docs/flowx-designer/overview.md)
- [FlowX.AI 5.13.0 Release Notes](https://docs.flowx.ai/release-notes/v5.x/v5.13.0-september-2026/v5.13.0-september-2026.md)
- [FlowX.AI 5.11.0 Release Notes](https://docs.flowx.ai/release-notes/v5.x/v5.11.0-august-2026/v5.11.0-august-2026.md)
- [Deployment guidelines v5.11](https://docs.flowx.ai/release-notes/v5.x/v5.11.0-august-2026/deployment-guidelines-v5.11.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.