Prompt Patterns for Extraction and Classification

Extraction (pulling specific structured fields out of unstructured text) and classification (assigning input to one of a fixed set of categories) are two of the most common tasks built with the OpenAI SDK in production applications — invoice parsing, ticket routing, content moderation, entity recognition. Both tasks share a property that shapes how their prompts should be written: the desired output has a small, well-defined shape, which means the prompt's main job is constraining the model to that shape reliably, not eliciting creative or open-ended reasoning. This lesson covers concrete, reusable patterns for both.

Why Extraction and Classification Need a Different Prompt Shape Than Open-Ended Tasks

An open-ended task like "write a product description" has many acceptable outputs; a classification task like "is this email spam or not spam" has exactly one correct answer per input, chosen from a fixed set. This changes what the prompt needs to do:

• The output format must be constrained tightly enough that downstream code can parse it without ambiguity.
• The set of valid categories or fields must be stated explicitly, not left for the model to infer from context.
• Edge cases (missing data, ambiguous category, no match) need an explicit instruction for what to output, because leaving this unspecified is one of the most common sources of production failures — the model inventing a plausible-sounding but wrong field value instead of indicating absence.

Pattern: Classification With a Constrained Category List

The foundational classification pattern states the exact category list and instructs the model to output only one of them, formatted for direct parsing:

from openai import OpenAI

client = OpenAI()

CLASSIFICATION_INSTRUCTIONS = """Classify the support ticket into exactly one of these categories:
billing, technical, account, other.

Respond with only the category name, in lowercase, with no punctuation
and no explanation."""

def classify_ticket(ticket_text: str) -> str:
    response = client.responses.create(
        model="gpt-5.6-terra",
        instructions=CLASSIFICATION_INSTRUCTIONS,
        input=ticket_text,
    )
    return response.output_text.strip().lower()

category = classify_ticket("I was charged twice for my subscription this month.")
print(category)  # billing

Three details in CLASSIFICATION_INSTRUCTIONS are load-bearing, not stylistic. First, the category list is enumerated explicitly (billing, technical, account, other) rather than described abstractly ("classify by topic") — an explicit, closed list is what makes "exactly one of these" enforceable; without it, the model has no fixed vocabulary to choose from and will produce inconsistent labels like "billing issue" versus "billing" across different calls. Second, "other" is included as an explicit escape category — without it, a ticket that doesn't cleanly fit billing, technical, or account forces the model to force-fit it into the nearest one, silently corrupting your category statistics. Third, the format instruction ("only the category name, in lowercase, with no punctuation") exists specifically so .strip().lower() in application code can safely compare the result against the known category strings without needing to handle variations like "Billing." or "Category: billing".

Pattern: Classification With Confidence or Abstention

Plain classification always returns one of the listed categories, even when the input is genuinely ambiguous. For applications where a wrong-but-confident answer is worse than an explicit "unsure" (routing a ticket to the wrong team causes more damage than flagging it for human review), add an abstention option and require the model to use it rather than guess:

CLASSIFICATION_WITH_ABSTENTION = """Classify the support ticket into exactly one of these categories:
billing, technical, account, other, uncertain.

Use "uncertain" only if the ticket genuinely does not provide enough
information to choose confidently among the other categories.

Respond with only the category name, in lowercase, with no punctuation."""

This is a small change in the instructions text but a meaningful change in what the application must handle: code that calls this version needs an explicit branch for "uncertain" that routes to human review rather than assuming every response is a final, actionable category. Adding this option without also adding the "use it only if genuinely unclear" qualifier tends to make the model overuse it — models given an easy escape hatch will sometimes prefer it even for cases they could actually classify correctly, so the qualifier is there to counteract that bias.

Pattern: Structured Extraction With an Explicit Field List

Extraction has the same "constrain the shape" goal as classification, but for several fields at once rather than a single label. State every field explicitly, including what to output when a field is absent from the input:

EXTRACTION_INSTRUCTIONS = """Extract the following fields from the invoice text below.
Respond with only a JSON object with exactly these keys:

- invoice_number (string)
- total_amount (number, no currency symbol)
- due_date (string, format YYYY-MM-DD)

If a field is not present in the text, use null for that field.
Do not include any keys other than the three listed above."""

def extract_invoice_fields(invoice_text: str) -> dict:
    import json
    response = client.responses.create(
        model="gpt-5.6-terra",
        instructions=EXTRACTION_INSTRUCTIONS,
        input=invoice_text,
    )
    return json.loads(response.output_text)

invoice = "Invoice #A-4471. Amount due: $230.00. Payment due by March 3, 2027."
fields = extract_invoice_fields(invoice)
print(fields)
# {'invoice_number': 'A-4471', 'total_amount': 230.0, 'due_date': '2027-03-03'}

The explicit null instruction for missing fields is the single most important line here for production reliability. Without it, a prompt asked to extract a due_date from text that has none will sometimes hallucinate a plausible-looking date rather than indicate absence, because the model has been instructed to produce a JSON object with that key and, absent other guidance, will try to fill it with something. Stating the fallback value explicitly turns an implicit, unreliable behavior into an explicit, checkable one: application code can reliably check fields["due_date"] is None to detect a genuinely missing value.

Note: For extraction tasks where field structure matters for downstream code, prefer the SDK's structured output support (a JSON schema passed via response_format or the equivalent typed-output parameter for your SDK version) over parsing free-form JSON text with json.loads. This lesson uses plain JSON-in-text for clarity of the underlying pattern; check your SDK version's documentation for the current structured-output mechanism, since this is an area that has changed across SDK releases.

Pattern: Extraction With Source Grounding

For extraction from longer or more ambiguous documents, requiring the model to quote the exact source span it extracted a value from makes incorrect extractions much easier to catch — a wrong value with no source text looks the same as a correct one until manually checked, but a wrong value paired with a source quote that clearly doesn't support it is easy to flag automatically or by a human reviewer:

GROUNDED_EXTRACTION_INSTRUCTIONS = """Extract the total amount due from the invoice text.
Respond with a JSON object with two keys:

- total_amount (number, or null if not found)
- source_quote (the exact sentence or phrase the amount was taken from,
  or null if total_amount is null)

Do not paraphrase source_quote; it must be an exact substring of the input."""

Application code can then verify the grounding cheaply, without another model call:

def verify_grounding(extracted: dict, original_text: str) -> bool:
    quote = extracted.get("source_quote")
    if quote is None:
        return extracted.get("total_amount") is None
    return quote in original_text

verify_grounding checks a simple, mechanical property — is the claimed quote actually present verbatim in the source document — which catches a meaningful class of extraction errors (the model paraphrasing, or extracting from a hallucinated value) without needing any additional model call or human review for the common case where grounding checks out.

Comparing the Extraction and Classification Patterns

Both patterns rely on the same underlying principle from earlier lessons — reducing ambiguity by making the exact valid output shape explicit rather than implied (Lesson 7 covers this principle more generally, including for tasks that are neither classification nor extraction).

Testing Extraction and Classification Logic

The parts of this code that do not require a live model call — output parsing, normalization, and grounding checks — should be tested directly with fake model output:

def test_grounding_passes_for_valid_quote():
    original = "Invoice #A-4471. Amount due: $230.00 by March 3."
    extracted = {"total_amount": 230.0, "source_quote": "Amount due: $230.00"}
    assert verify_grounding(extracted, original) is True
    print("PASS: valid quote found in source text")

def test_grounding_fails_for_fabricated_quote():
    original = "Invoice #A-4471. Amount due: $230.00 by March 3."
    extracted = {"total_amount": 500.0, "source_quote": "Amount due: $500.00"}
    assert verify_grounding(extracted, original) is False
    print("PASS: fabricated quote correctly flagged as ungrounded")

def test_null_total_requires_null_quote():
    extracted = {"total_amount": None, "source_quote": None}
    assert verify_grounding(extracted, "any text") is True
    print("PASS: null total with null quote is considered valid")

test_grounding_passes_for_valid_quote()
test_grounding_fails_for_fabricated_quote()
test_null_total_requires_null_quote()

This test suite exercises verify_grounding against hand-constructed extraction results, exactly mimicking both a correct and an incorrect model response, without spending any API quota. This is the dependency-injection pattern that matters throughout prompt engineering testing: the function under test takes plain data as input, so tests supply that data directly instead of needing a real model call to produce it.

Common Mistakes

Omitting an explicit fallback for missing or ambiguous cases. Both classification and extraction prompts that do not specify what to output for absent data or ambiguous input tend to produce confidently wrong answers instead of clear signals that a case needs special handling.

Leaving output format loosely specified. Instructions like "return the category" without specifying exact casing, punctuation, or whether to include an explanation lead to inconsistent output that breaks naive string comparison or JSON parsing in application code.

Skipping grounding or validation for high-stakes extraction. Trusting extracted values without any mechanism to catch hallucinated fields is acceptable for low-stakes internal tools, but risky for anything that feeds financial, medical, or legal downstream processing.

Best Practices

Enumerate the full category or field list explicitly in the prompt. Do not rely on the model inferring an implicit taxonomy; state every valid category or field name directly.

Always specify the behavior for missing, ambiguous, or out-of-scope input. An explicit "other," "uncertain," or "null" instruction converts an unhandled edge case into a defined, testable behavior.

Add source grounding for extraction tasks feeding critical downstream systems. Requiring an exact-quote field lets application code mechanically verify extracted values against the source text without an additional model call.