Define categories before writing questions
A Choice suits an exclusive category: invoice, contract, correspondence or other. If a document can be both confidential and urgent, use separate yes/no questions for those flags. The primitive documentation distinguishes an exclusive choice from independent Noul judgments.
Write category definitions that address boundary cases. For example, decide whether a quote belongs with invoices and whether an email containing a contract attachment is classified by its message or attachment. When a hierarchy is necessary, the official classification recipe provides a starting pattern.
Extract text locally and preserve the original
The documented Jev model is text-only. A PDF, scan or office document therefore needs a parser or OCR stage first. Keep page locations and document identifiers so a reviewer can find the evidence that produced a judgment.
Empty, unreadable and unsupported inputs are preprocessing failures, not meaningful categories. Route them to a separate processing queue. Do not conceal an OCR failure by labeling the document “other.”
A typed Python category example
This example uses the official SDK, reads TYPESAFE_API_KEY, makes one billable request when run, and prints a proposed queue. The review threshold is illustrative and must be evaluated on your own labeled documents.
from typesafe_sdk import Choice, TypeSafeClient
REVIEW_AT = 0.85 # Example policy, not a universal threshold.
with TypeSafeClient() as client:
response = client.system_one(
state={"document": "Invoice for document hosting, due next month."},
questions={
"category": Choice(
instructions="Classify document by its main purpose.",
criteria={
"invoice": "A request for payment for goods or services",
"contract": "An agreement establishing obligations",
"correspondence": "A message without those purposes",
"other": "None of the listed purposes",
},
)
},
)
answer = response.choices["category"]
queue = (
"review"
if answer.confidence is None
or answer.confidence < REVIEW_AT
or answer.choice == "other"
else answer.choice
)
print(queue)The snippet does not move or delete files. Before adding those actions, validate transport failures and response shape, keep originals recoverable and record the model version. API failures should leave the item unprocessed rather than silently applying a category.
A community application to inspect
Jev Document Classification describes local text extraction, typed judgments through Vercel AI Gateway, review and unprocessable buckets, and preview/undo behavior. “Local-first” here does not mean its model inference is offline. Inspect the gateway settings and exactly which text is sent.
Evaluate such an application separately from the model: a correct category cannot compensate for overwriting a file, mixing up document IDs or losing the link to the original.
A useful validation set
- Clear examples and near-boundary cases for every category.
- Documents outside the taxonomy and mixed-purpose documents.
- Empty scans, poor OCR and unsupported formats.
- Relevant languages and vocabulary from your actual users.
- Text that tries to instruct the classifier to choose a label.
Measure per-category mistakes and the share routed to review. Confirm whether reviewers can recover the relevant page. The official failure notes describe adversarial and context-related limitations; typed output is not a security guarantee.