Span Boundary Confidence Annotation Prompt

Use this prompt when the exact character positions of an extracted value matter as much as the value itself. Span boundary confidence annotation is designed for extraction engineers who need to know not just what was extracted, but whether the model is certain about where the extraction starts and ends. This matters in legal clause boundaries where a single word changes obligation scope, contract dates where an adjacent number alters the effective period, clinical measurements where unit boundaries affect dosage interpretation, and financial figures where digit grouping changes magnitude. If your downstream system consumes span offsets for highlighting, citation anchoring, or record assembly, boundary errors cause cascading failures that are expensive to detect and repair after ingestion.

This prompt is not the right choice when you only need field values without positional provenance. If your pipeline treats extracted text as opaque strings and never renders source highlights, generates citation anchors, or assembles records from overlapping spans, a standard field extraction prompt with per-field confidence scores will be simpler, faster, and cheaper. Similarly, if your documents have unambiguous field delimiters—key-value pairs with colons, form fields with labels, or tabular data with consistent separators—boundary annotation adds overhead without benefit. Reserve this prompt for unstructured or semi-structured text where entity boundaries are genuinely ambiguous: run-on legal prose, clinical narratives, conversational transcripts, or documents where the same value could reasonably be parsed with different start and end positions.

Before deploying this prompt, confirm that your downstream consumers can act on boundary confidence signals. The prompt produces left-boundary and right-boundary confidence scores, ambiguity flags, and alternative boundary candidates. If your application only stores a single span per field and discards the confidence metadata, you are paying the token and latency cost of boundary annotation without using its output. Wire the boundary scores into your ingestion pipeline: route high-confidence spans directly to your system of record, flag ambiguous spans for human review, and use alternative candidates to power a disambiguation UI where reviewers select the correct boundary. For regulated domains, retain the boundary confidence trail as audit evidence that ambiguous spans were identified and resolved rather than silently ingested.

Start with a narrow scope. Pick one field type where boundary errors have caused production incidents—contract effective dates, financial amounts, or medication dosages—and run this prompt against a labeled dataset where you know the correct span boundaries. Measure boundary precision and recall separately from value accuracy. A model can extract the correct dollar amount while misaligning the span by one character, and that one-character error might break a downstream parser. Use the eval results to decide whether boundary annotation should become a standard layer in your extraction architecture or remain a targeted tool for high-risk fields.

This template is the core instruction you send to the model. It enforces a strict output contract: every extracted span must carry a boundary_confidence score, a fuzzy_boundary flag, and a list of alternative_spans when the model is uncertain. The prompt is designed to be self-contained so that you can copy it, replace the placeholders, and get structured, auditable results without additional system prompts.

textCopy
You are a precise span extraction engine. Your task is to extract spans from the provided text that match the target entity type, and annotate each span with boundary confidence information.

## INPUT
[INPUT_TEXT]

## TARGET ENTITY
[ENTITY_TYPE]

## OUTPUT SCHEMA
Return a JSON object with an "extractions" array. Each extraction must follow this schema exactly:
{
  "span_text": "string (the exact text of the extracted span)",
  "start_char": integer,
  "end_char": integer,
  "boundary_confidence": float (0.0 to 1.0, where 1.0 means perfectly certain about the exact start and end characters),
  "fuzzy_boundary": boolean (true if the start or end character position is uncertain),
  "boundary_notes": "string (explain why the boundary is fuzzy, or 'clear' if not)",
  "alternative_spans": [
    {
      "span_text": "string",
      "start_char": integer,
      "end_char": integer,
      "rationale": "string (why this alternative is plausible)"
    }
  ]
}

## CONSTRAINTS
- Extract every instance of [ENTITY_TYPE] found in the text. Do not skip any.
- `start_char` and `end_char` must be 0-indexed character offsets into the original [INPUT_TEXT].
- If you are completely certain about the span boundaries, set `boundary_confidence` to 1.0, `fuzzy_boundary` to false, and `alternative_spans` to an empty array.
- If the boundaries are ambiguous, set `fuzzy_boundary` to true, provide a `boundary_confidence` below 1.0, and include at least one `alternative_spans` entry with a plausible different span.
- Do not invent spans that are not present in the text. If no spans are found, return an empty "extractions" array.
- Do not include any text outside the JSON object.

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

After pasting the template, replace [INPUT_TEXT] with the document or passage you are extracting from. Set [ENTITY_TYPE] to the category of span you want—such as "person name," "monetary amount," or "drug dosage." Provide [FEW_SHOT_EXAMPLES] as inline JSON examples showing correct extractions with boundary annotations for your domain. Set [RISK_LEVEL] to "low," "medium," or "high" to control the model's conservatism: at "high," the model should lower confidence and expand alternatives for any boundary ambiguity. For production use, always validate the output JSON against the schema before ingestion, and route any record where fuzzy_boundary is true to a human review queue if the downstream risk warrants it.

The Span Boundary Confidence Annotation Prompt is designed to sit inside a production extraction pipeline where span precision is critical. Unlike field-level extraction, this prompt returns character-level boundary annotations, confidence markers, and alternative span candidates. The harness must treat the output as a structured artifact that downstream systems can validate, compare against ground truth, and route for review when boundary confidence falls below acceptable thresholds. The primary integration points are: a pre-processing step that normalizes input text and preserves original character offsets, the model call itself with strict output schema enforcement, a post-processing validator that checks span overlap, boundary consistency, and confidence score ranges, and a routing decision that sends low-confidence spans to a human review queue.

Start by wrapping the prompt in a function that accepts [INPUT_TEXT], [TARGET_ENTITY_TYPE], and [CONFIDENCE_THRESHOLD] as parameters. The model should be called with response_format set to a JSON schema that enforces the output contract: an array of span objects, each containing span_text, start_char, end_char, boundary_confidence (0.0–1.0), boundary_flags (an array of enum values like FUZZY_START, FUZZY_END, OVERLAPPING_CANDIDATE), and alternative_spans (an array of objects with span_text, start_char, end_char, and confidence). After the model responds, run a boundary validator that checks: (1) all start_char and end_char values are within the input text length, (2) span_text matches the substring at those offsets, (3) no two primary spans overlap unless explicitly flagged, (4) boundary_confidence is a float between 0 and 1, and (5) alternative spans also pass offset validation. If validation fails, retry once with the validation error message appended to the prompt as a correction hint. If the retry also fails, log the failure and escalate the entire document to human review rather than silently accepting broken spans.

For observability, log every extraction call with: the prompt version hash, model ID, input text length, number of spans returned, average boundary confidence, count of spans flagged as fuzzy, count of spans below threshold, validation pass/fail status, retry count, and latency. Emit these as structured logs or metrics so you can detect drift in boundary confidence distributions over time. For human review routing, configure a queue that receives spans where boundary_confidence < [CONFIDENCE_THRESHOLD] or where boundary_flags is non-empty. Each review item should include the original sentence, the model's primary span, all alternative spans, and a pre-filled form for the reviewer to confirm or adjust boundaries. Track review decisions to build a boundary accuracy eval dataset. Avoid wiring this prompt directly into a synchronous user-facing flow without a timeout and fallback—boundary annotation on long documents can be latent, and a stuck model call should degrade gracefully to a partial result or an escalation message rather than blocking the user.