Document Classification

POST /lmkit/v1/categorize assigns a document to YOUR taxonomy: the categories arrive in the request, the model classifies against them, and the answer routes the document to its schema, its queue, and its retention rule. This is the router of the IDP pipeline, and its defining property is that the taxonomy is a request parameter: adding a document class to your operation is an edit to a JSON array, not a training project, a deployment, or a wait.

1The contract#

• input: the document itself: plain text, a base64-encoded file, or a file id, including one minted by intelligent splitting. Whole documents are the intended input; the shared pipeline (format handling, OCR) runs inside the endpoint.
• categories: your class names, in your vocabulary.
• category_descriptions: one line per category, and the accuracy lever of the whole endpoint. The model classifies against the DESCRIPTION, not the bare word: "Billing: invoices, payment reminders, account statements" separates cleanly from "Contracts: agreements, amendments, signed orders" where the bare labels would blur.
• allow_unknown_category: the open-set switch. With it true, a document matching nothing comes back unmatched instead of force-filed into the least-wrong class; route those to a human and they become tomorrow's new category.
• max_categories: how many top matches to return (default 1). More than one turns classification into tagging: a document can be both "Invoice" and "Dispute correspondence".
• guidance: interpretation rules that apply across the taxonomy ("classify by the SENDER's intent, not the subject line").

The response is the matched category values, in your exact vocabulary, ready to switch on.

2Writing taxonomies that classify well#

• Describe, always. The descriptions are where accuracy lives; a taxonomy without them is running at a fraction of its potential. State what belongs AND what borders it: "Expense receipts: purchases by employees; NOT supplier invoices".
• Keep classes mutually exclusive at one level. "Invoice" beside "Urgent" mixes two axes; run two classification calls (document type, then urgency) and each stays sharp.
• Let unknown be unknown. Closed-set classification (allow_unknown_category: false) is right only when the taxonomy is genuinely exhaustive, as in a two-way sort. Everywhere else, forced filing hides exactly the documents that most need eyes.
• Two levels want dependent values. When a category has subcategories, classify in one extraction call with a dependent-enum schema: the pair generates as one unit and an undeclared combination cannot be produced.

3Classification in the pipeline#

The classic IDP chain gives each segment from splitting a class, and the class selects everything after:

• the extraction schema: invoices fill the invoice schema, contracts the contract schema; structured extraction does the reading.
• the business route: which queue, which system, which SLA; segment labels from splitting arrive as a useful prior, and the classification is the decision.
• search metadata: the class stored as filterable metadata turns "somewhere in the archive" into "invoices from March".

Beyond routing documents, the same endpoint triages support messages, sorts email exports, and files anything else the analysis toolbox reads, with the same request shape.

4Volume, models, and the escalation path#

Classification runs per document at mailroom volume, which makes it the natural home of compact, fast models: the task is constrained, and a described taxonomy does most of the work. Set the default in Models, measure on a labeled sample of your own traffic, and escalate model size only where your actual categories measurably confuse it. When one category system carries real volume, the durable investment is fine-tuning a compact model on your corrected classifications: your taxonomy becomes the model's native language, at small-model speed.

5Stated plainly#

• The taxonomy is a request parameter: your categories, your descriptions, changed as easily as the request that carries them.
• Descriptions are the accuracy lever, and allow_unknown_category keeps the open-set question honest.
• Classification is the router of the pipeline: it picks the schema, the queue, and the metadata, which is why it sits between splitting and extraction.