IDP — Build Classifier

IDP — Build Classifier

Type: idp-build-classifier  ·  Package: IDP Activities v1.20.4  ·  Output: object

Since: v1.2.0

Builds the schema that identifies which kind of document you are looking at, from the list of taxonomies you know. You run it through AI — Extract before extracting, and the playbook decides whether to carry on.

The normal flow no longer uses it

IDP — Classify classifies each page (its type and whether it starts a document) internally, so it does not need this activity. IDP — Build Classifier stays as a low-level piece for anyone building classification by hand.

Why this is needed

Because IDP — Ground does not cover this case, and it is worth understanding why.

Grounding verifies “this text is written in the document”. It does not verify “this document is the type I think it is”. If you give a purchase order to an invoice taxonomy:

• If you are lucky, the model returns null for everything and the whole document goes to review. Costly (a person looks at it) but nothing bad is stored.
• If you are not, the purchase order carries a number that looks like an invoice number. The model fills it in. And grounding confirms it, because that text really is in the document. High confidence, accepted automatically, wrong data stored without anyone seeing it.

That second case is what justifies classifying first.

How it works

It validates each taxonomy (the same rules as IDP — Build Schema), checks that no two share the same documentType and builds a JSON Schema with an enum of types that always includes unknown. It does not call the model: the log only says how many types it was built for.

Required parameters

Parameter	Type	Default	Description
taxonomies	string | List	—	The taxonomies to choose between: paths to .json files, the JSON as text or the objects. A single one is fine too. Their documentType and description are what the model reads to tell them apart.

Optional parameters

None.

Output

Returns an object with the JSON Schema, ready to pass as schema to AI — Extract. The model’s answer with that schema carries two fields:

Field	What it is
documentType	One of your taxonomies’ documentType values, or "unknown".
reason	What in the document made it decide that.

The enum builds itself

The list of types comes from the taxonomies themselves, so it cannot drift out of sync: you add a new type and the classifier knows it without you touching anything. Each taxonomy’s description is passed to the model as context to tell them apart, which is another reason to write it well.

unknown is not decoration

Without an honest way out, a model given a closed list picks the least bad one. That is why unknown is always in the enum and the model is told explicitly not to pick the closest match. A document you don’t recognise is a correct result; a misclassified document is not.

It asks for a reason, not a confidence

Consistent with the rest of the package: the confidence a model assigns itself is not calibrated, and here there is nothing to locate in the document to measure it for real — it would be a number that invites trust without grounds. unknown is its honest way of saying it does not know.

reason is useful: classification comes out better when the model has to justify it, and when a batch gets misclassified, it is what tells you why without opening the documents by hand.

Example

IDP — Build Classifier   taxonomies = [asset("taxonomies/invoice.json"), asset("taxonomies/purchase-order.json")]   → output: classifier

IDP — Load Document      path = docPath   → output: doc
AI — Extract             prompt = doc["text"]
                         schema = classifier
                         model  = "claude-haiku-4-5"
                         → output: kind
If   condition = kind["documentType"] == "supplier-invoice"
  ...extract with the invoice taxonomy
Else
  Log   message = "Discarded: " + kind["documentType"] + " — " + kind["reason"]

Classifying is cheap: the document goes in once and the answer is two fields, so a small model is enough. What it really saves is what it prevents — not paying for the full extraction of a document that did not belong.

Common errors

Message	Cause and fix
'taxonomies' is required. / 'taxonomies' is empty; there is nothing to tell apart.	No taxonomy was passed.
Two taxonomies declare the same documentType '…'. The model cannot tell apart two kinds with the same name.	Two taxonomies with the same documentType (case-insensitive). Rename one.
'taxonomy' is not valid JSON: … / The taxonomy must declare a 'documentType'. / Field '…' has no 'description'. …	A taxonomy is invalid. See the errors in IDP — Build Schema.

Related activities

• IDP — Build Schema — the next step, once you know what it is.
• IDP — Classify — ready-to-use per-page classification.
• IDP — Ground — verifies the values, not the document type.