Handwritten Text Detection Prompt for OCR Routing

This prompt is designed for document intelligence platform teams who need to classify individual document pages or image regions as containing handwritten text, printed text, or a mix of both. The classification output determines whether the page is routed to a specialized handwriting recognition model (such as Amazon Textract's handwriting mode, Google Document AI's handwriting processor, or a fine-tuned TrOCR model) or a standard OCR pipeline optimized for machine-printed text. Standard OCR models trained predominantly on printed fonts degrade sharply on cursive, block capitals, and low-contrast handwriting. Sending handwritten pages through a print-optimized pipeline produces garbled output that silently corrupts downstream extraction. Conversely, routing printed pages through handwriting models wastes compute and can introduce transcription errors where the model overfits to stroke-like features in serif fonts.

This prompt operates as a binary or ternary classifier at the ingress layer of a document processing pipeline. It accepts a page image and returns a content type label, a confidence score, and an optional region map for mixed-content pages. The output feeds directly into a routing dispatcher that selects the appropriate OCR model per page or per region. Use this prompt when your ingestion pipeline handles heterogeneous document types (forms, letters, invoices, notes), when you operate separate OCR models for handwriting and print with different cost or latency profiles, when you need page-level routing decisions before committing to expensive GPU inference, or when you process scanned documents where handwritten annotations, signatures, or margin notes appear alongside printed text.

Do not use this prompt when you have a single unified OCR model that handles both handwriting and print adequately, when your documents are exclusively born-digital PDFs with no handwriting, when you need character-level or word-level handwriting detection rather than page-level classification, or when latency constraints require sub-100ms decisions without a vision model call. For mixed-content pages where handwriting appears in small regions alongside printed text, consider whether region-level classification with bounding box outputs is necessary rather than a single page-level label. If your pipeline already performs layout analysis, you may be able to combine this classification step with existing region detection to avoid redundant model calls.

This prompt template is designed to be pasted directly into your system prompt or a dedicated classification step in your document intelligence pipeline. It instructs the model to analyze an image of a document page and determine whether it contains handwritten text, printed text, or a mix of both. The output is a structured JSON classification that your application can use to route the page to a standard OCR model, a specialized handwriting recognition model, or a hybrid processing path. The square-bracket placeholders allow you to configure the confidence thresholds, output schema, and routing labels to match your specific infrastructure without rewriting the core instruction.

textCopy
You are a document image classifier for an OCR routing system. Your task is to analyze the provided document page image and determine the presence and type of text content.

## INPUT
[IMAGE]: A single document page image, which may be a scan, a photo, or a born-digital page.

## CLASSIFICATION TASK
Analyze the image and classify the text content into one of the following categories:
- `printed_only`: The page contains only machine-printed or typeset text.
- `handwritten_only`: The page contains only handwritten text.
- `mixed`: The page contains a combination of printed and handwritten text.
- `no_text`: The page contains no detectable text.

## DETAILED INSTRUCTIONS
1. Examine the entire page, including margins, annotations, signatures, and stamps.
2. Distinguish handwriting from decorative or script fonts by looking for irregular character shapes, inconsistent baselines, and variable spacing.
3. If the page is mostly printed but contains a signature or a short handwritten note in the margin, classify it as `mixed`.
4. If the page is a pre-printed form filled out by hand, classify it as `mixed`.
5. If you are uncertain, reflect that in the confidence score rather than guessing.

## OUTPUT_SCHEMA
Return a single JSON object with the following fields:
{
  "classification": "printed_only" | "handwritten_only" | "mixed" | "no_text",
  "confidence": 0.0-1.0,
  "handwriting_percentage": 0-100,
  "rationale": "A brief, one-sentence explanation of the classification decision.",
  "routing_label": "[PRINTED_QUEUE]" | "[HANDWRITING_QUEUE]" | "[HYBRID_QUEUE]" | "[REVIEW_QUEUE]"
}

## ROUTING RULES
- If `classification` is `printed_only` and `confidence` is above [CONFIDENCE_THRESHOLD], set `routing_label` to "[PRINTED_QUEUE]".
- If `classification` is `handwritten_only` and `confidence` is above [CONFIDENCE_THRESHOLD], set `routing_label` to "[HANDWRITING_QUEUE]".
- If `classification` is `mixed`, set `routing_label` to "[HYBRID_QUEUE]".
- If `classification` is `no_text` or `confidence` is below [CONFIDENCE_THRESHOLD], set `routing_label` to "[REVIEW_QUEUE]".

## CONSTRAINTS
- Do not perform OCR or transcribe any text.
- Do not describe the content of the text beyond what is necessary for classification.
- If the image quality is too poor to make a determination, set `confidence` to a low value and route to `[REVIEW_QUEUE]`.

To adapt this template for your environment, replace the bracketed placeholders with your actual queue names and thresholds. Set [CONFIDENCE_THRESHOLD] to a value like 0.85 to start, then tune based on your eval results. Replace [PRINTED_QUEUE], [HANDWRITING_QUEUE], [HYBRID_QUEUE], and [REVIEW_QUEUE] with the actual topic names, queue ARNs, or workflow identifiers your downstream system expects. If your pipeline uses a different routing mechanism, you can replace the routing_label field with a target_model or pipeline_id field. For high-stakes document processing where misclassification could cause data loss, always route mixed and low-confidence pages to a human review step before automated extraction.

This prompt is designed as a classification gate before OCR execution. In a production pipeline, the model call should be wrapped in a service that accepts an image or document page, invokes the prompt, parses the structured JSON response, and routes the page to either a handwriting-specific OCR model (e.g., Amazon Textract with handwriting analysis, Google Document AI with handwriting recognition, or a fine-tuned TrOCR model) or a standard printed-text extraction pipeline. The routing decision should be based on the classification field and the handwriting_confidence score, not on raw model logprobs, to keep the decision boundary explicit and auditable.

Implement a validation layer immediately after the model response that checks: (1) the output is valid JSON matching the expected schema, (2) the classification field is one of the allowed enum values (handwritten, printed, mixed), (3) the handwriting_confidence is a float between 0.0 and 1.0, and (4) the regions array, if present, contains valid bounding box coordinates. If validation fails, retry once with a repair prompt that includes the validation error message and the original image. If the retry also fails, route the page to a manual review queue and log the failure with the page ID, model response, and validation errors for debugging. For mixed classifications, extract the region coordinates and crop the page into handwriting and print zones before routing each crop to the appropriate OCR model.

Model choice matters here. Use a vision-capable model (GPT-4o, Claude 3.5 Sonnet, or Gemini 1.5 Pro) rather than a text-only model receiving OCR pre-pass output, because the prompt needs to reason about visual features like stroke variation, baseline consistency, and connected characters that OCR engines often strip. Set temperature=0 for deterministic classification. For high-throughput pipelines processing thousands of pages per hour, consider batching multiple page images into a single request with a page-indexed output schema, or deploy a lightweight classifier model (e.g., a fine-tuned ViT or ConvNeXt) for the initial detection and reserve the LLM call for ambiguous cases where the lightweight model's confidence falls below a threshold. Log every classification decision with the page ID, confidence score, model version, and routing outcome to build a dataset for evaluating classification drift over time.

Human review should be triggered when handwriting_confidence falls between 0.4 and 0.6, when the classification is mixed with conflicting region predictions, or when the model explicitly sets requires_review: true. Route these cases to a review queue with the original image, the model's classification, and the confidence score, and allow reviewers to override the routing decision. Track override rates by confidence bucket to calibrate the review threshold. For regulated document workflows (healthcare, legal, finance), require human confirmation on any page classified as handwritten before routing to OCR, because handwriting OCR errors in regulated contexts can propagate downstream into extracted fields, summaries, and decisions. The harness should emit structured logs with trace IDs that connect the classification decision to the downstream OCR output and any human corrections, creating an audit trail from ingestion to extraction.