Extract Reference Codes with Explicit Text Rules

An AI assistant asked to extract a reference code needs a more precise instruction than find the ticket number. A message may contain a code-like substring, several repeated occurrences, a different letter case or digits that look familiar but use another character set. The extraction task is to identify text according to a declared rule. It does not establish that a ticket exists, that the sender owns it or that a workflow may act on it.

This guide develops an original fictional code family, TK followed by a hyphen and four ASCII digits. The codes and messages are authored examples, not customer records or observed model responses. Local Python checks compare two declared matching tasks with manual expectations. No ticket system is queried and no records are changed. The exercise helps a person write a narrow extraction brief, preserve the evidence in the original text and distinguish a matching result from a business decision.

Choose between a whole-field check and a text search

A whole-field check asks whether the entire supplied string follows the rule. A text search asks where qualifying occurrences appear inside a longer string. Those are different operations. The fictional value TK-0042 can satisfy the whole-field rule. A sentence containing that value may contain a valid occurrence without being a valid standalone field. Asking an assistant to validate a sentence as a ticket number leaves those two intended tasks unclear.

For this exercise, the whole-field rule is exactly uppercase TK, one ordinary hyphen and four characters from zero through nine, with nothing before or after. The regular expression is TK-[0-9]{4}, applied with Python re.fullmatch. Python's documentation distinguishes fullmatch from searching operations. That API behavior is a limited technical reference; the actual format and business meaning of the fictional code family are choices made for this exercise, not an industry standard.

The text-search rule uses the same code shape but rejects an immediately adjacent ASCII letter, ASCII digit or underscore on either side. Its Python pattern is (?<![A-Za-z0-9_])TK-[0-9]{4}(?![A-Za-z0-9_]). The rule deliberately names the neighboring characters it considers. It does not claim to recognize every natural-language word boundary or every writing system. Later cases show the consequence of that choice instead of treating the phrase standalone code as a complete specification.

Record the two tasks separately in a handoff. A field named whole_field_match can hold a boolean, while occurrences can hold the matched strings and their source spans. Do not use one general valid flag for both. A reader otherwise cannot tell whether the original field passed a format rule or whether a suitable substring was found somewhere within a larger message. Neither result alone validates a real-world identifier against a system of record.

State the character rules before normalizing the input

The prefix in the authored rule is uppercase TK. The separator is the ordinary hyphen character, and the four digits are ASCII characters zero through nine. Leading and trailing whitespace are not removed before the whole-field check. These are intentionally strict teaching choices. Another interface may allow lowercase input, a different separator or trimming, but it needs to state those transformations. An assistant should not make them silently because they appear to improve a match rate.

Python's regular-expression documentation describes different character classes and flags, including Unicode-sensitive behavior. In this exercise, the explicit [0-9] range makes the intended digit set visible. The lesson is to select the class that matches the contract rather than assume a familiar shorthand always means the same thing in every engine or mode. The patterns here are checked with Python's built-in re module; no claim of identical behavior across other regular-expression engines is made.

Keep the original text if a transformation is authorized. If a later task permits case conversion or whitespace removal, store the original and transformed values separately and record the rule. That makes it possible to explain why an input that originally failed later matched. A normalized code can be useful for a particular interface while still being unsuitable evidence for a claim about what the sender actually typed. The extraction note should preserve that difference.

Do not use visual similarity as an identity rule. A character that resembles a digit or letter may be a different code point. This guide does not perform confusable-character detection or make a security finding. Its small examples simply show that an explicitly selected character set has consequences. If a real workflow needs broader Unicode handling, define and evaluate that task separately instead of enlarging this pattern and assuming the larger result is automatically correct.

Preserve occurrences and source locations

An extraction result should make it possible to find the matched text again. The fictional expectations therefore include start and end positions in the Python string, with the end position excluded. These positions describe the string supplied to the local check. They are not byte offsets into an exported file or positions in a rendered screenshot. A downstream application must use the same indexing basis before it treats a pair of numbers as a reliable locator.

Retain repeated occurrences when the task is to extract mentions. Two appearances of TK-0042 are two occurrences of the same authored string. Removing the second occurrence changes an occurrence list into a unique-value list. Both views can be useful, but they answer different questions. A task that asks which messages mention a code may need source context for every occurrence, while a task that asks which distinct code strings appear may need a separate deduplicated view.

Preserve the order returned by the declared traversal of the text. Reordering results alphabetically can hide where a mention occurred or how two references relate in a sentence. If sorting is requested, retain the original positions with the sorted values. The exercise does not infer that the first code is the current code or that a later code supersedes an earlier one. Those meanings would require additional context and a separate interpretation rule.

Treat the source span as evidence about extraction, not authority to act. A matched code in an email body might be quoted from an earlier exchange, presented as an example or explicitly denied. The lexical pattern does not distinguish those contexts. A workflow can first extract candidate mentions, then evaluate the surrounding statement through its own defined process. Skipping that second question can turn a correct text match into an incorrect operational action.

Work through exact and embedded matches

Case A is the authored string TK-0042. The whole-field expectation is true. The text-search expectation contains one occurrence, TK-0042, beginning at position zero and ending at position seven. There are seven characters because the prefix contributes two, the hyphen one and the digits four. This is a format example only. The existence or status of a real ticket with a similar label has not been checked.

Case B is the invented sentence See (TK-0042). The whole-field expectation is false because the string contains more than the code. The text-search rule finds one occurrence from position five to position twelve. Parentheses and the final period do not belong to the match. They also do not violate the declared neighboring-character restriction. The example illustrates why a text-search result should preserve the matched substring rather than return the entire sentence as the extracted identifier.

Case C is XTK-0042. It fails the whole-field rule and yields no text-search occurrence because the immediately preceding X is an ASCII letter. A simpler search for TK-[0-9]{4} would find a substring, but that is not the selected text-search rule. Neither pattern is inherently the correct interpretation of all references. The specification decides whether embedded forms should count, and the case makes the chosen rejection visible.

Case D is TK-00420. It has five digits after the hyphen. The whole-field rule rejects it, and the text-search rule does not accept its first seven characters because another ASCII digit immediately follows. Without the trailing restriction, a search could return TK-0042 from the longer code-like value. The bounded question is whether that truncation is allowed. This exercise says it is not; it does not silently shorten an input to force a match.

Use near misses to expose hidden transformations

Case E is tk-0042. Both selected tasks reject it because the authored prefix rule is case sensitive. A proposed case-insensitive variant would be a changed rule, not merely a more helpful implementation of the same rule. If the intended system accepts lowercase references, revise the specification and expectations together. Do not describe the rejected lowercase case as a model failure unless the model was actually tested against a different, clearly stated requirement.

Case F uses the visible prefix TK followed by a hyphen and the Arabic-Indic digits ٠٠٤٢. Both expectations are negative under the explicit ASCII-digit rule. The digits can express a familiar number while remaining outside [0-9]. The fixture includes the original characters so that a reader can inspect the actual input rather than rely on a verbal description. It does not propose a universal language policy or judge whether another application's broader digit support is appropriate.

Case H is TK-0042 followed by a newline. It does not satisfy the whole-field check because the newline is part of the supplied string. The text-search task still finds the seven-character code from zero to seven. This difference is useful when an assistant has silently stripped a trailing line break before validation. If stripping is desired, state that preprocessing step and distinguish the result from validation of the original unmodified field.

Case J is TK-0042_suffix. The underscore is one of the explicitly excluded neighbors, so no text-search match is accepted. An instruction that says punctuation is allowed around codes would be too broad for this contract because the underscore has a special role in the chosen boundary class. Use representative adjacent characters in the practice set. The examples should explain the actual rule rather than rely on a general description that conceals its exceptions.

Keep repeated mentions and Unicode surroundings visible

Case G is TK-0042 TK-0042. The whole-field result is false. The text-search result contains two occurrences: positions zero through seven, then eight through fifteen. The space separates the mentions. The repeated values remain in the authored expected list. If a downstream summary wants one distinct code string, it can create that separate view while retaining the occurrence evidence. The two mentions do not imply that two different tickets exist.

Case I is αTK-0042β, using Greek letters around the fictional code. It fails the whole-field check but produces one text-search occurrence from position one to position eight. That result may surprise a reader who interpreted standalone as outside every kind of word. The declared neighboring restriction covers ASCII letters, digits and underscore; it does not include those Greek letters. The local result follows that narrow rule and exposes why the plain-language description must be precise.

If the desired behavior is to reject the I match, change the boundary requirement rather than dismiss the result as an inexplicable engine error. A broader character policy could be appropriate, but it needs its own examples and engine-specific definition. The present guide does not substitute a new policy after seeing the outcome. Keeping the surprising case demonstrates the difference between a specification that people misunderstood and an implementation that violated the specification.

Use the same discipline when an AI assistant proposes a regular expression. Ask it to explain a near miss and a surprising accepted case, then compare the explanation with an independent execution of the actual pattern. A natural-language explanation can be plausible while describing a different rule. The fixture supplies manually specified expectations and local Python results for these ten strings; it supplies no observed AI answer and therefore makes no claim about any model's accuracy.

Decide what a consumer should do when the occurrence list contains several different candidate strings. Selecting the first occurrence is a policy choice, not a property of regular-expression matching. A message could mention a previous reference before the current one. A bounded extractor can return all candidates and leave selection unresolved, or follow an explicitly supplied selection rule with its own examples. Do not invent surrounding context in order to force one candidate into a field that was designed for a single value.

Write a bounded extraction brief for an assistant

An original teaching brief can say: treat each supplied input as an unchanged Python string; report whether re.fullmatch accepts TK-[0-9]{4}; separately use the declared ASCII-neighbor pattern with re.finditer; return every matched string and its start/end-exclusive span in source order; do not trim, case-fold, deduplicate or query a ticket system. These instructions are authored for the exercise. They are not a company policy, an observed prompt test or permission to process real messages.

Ask the assistant to identify ambiguities before generating an implementation. Relevant questions include whole-field versus embedded search, allowed character sets, neighbor rules, repeated mentions, indexing basis and permitted transformations. A short explicit answer to each is more useful than a claim that the pattern handles all edge cases. The ten examples are selected boundaries, not an exhaustive characterization of every possible input or an assessment of performance on large or hostile text.

Specify the output shape as well. A useful teaching record has case identifier, original input, whole-field result and an ordered occurrences array. Each occurrence contains text, start and end. A no-match result should be an empty array rather than a fabricated code, while a malformed input should be handled according to a separately defined input contract. This fixture contains strings only and does not exercise nulls, byte strings, file encodings or arbitrary object inputs.

Keep the extraction stage read only when the task is merely to identify mentions. A later lookup or update needs a different contract and the relevant authorization. Do not let the presence of a code-like value turn a drafting exercise into a request to retrieve account data or alter a record. The guide's examples stop at lexical results. They do not verify ownership, existence, status, uniqueness across a business system or permission to act.

Reproduce the fixture and review the handoff

The CSV contains ten original strings and manually declared whole-field expectations. The JSON carries the two literal patterns and the expected occurrence arrays, including spans. Local Python 3.12 checks compare fullmatch and finditer results with those expectations. The downloadable files are practice data; no executable utility is supplied. Their purpose is to make the chosen rules inspectable without connecting to a service or presenting a generated explanation as the sole evidence of correctness.

Compare exact strings before comparing a summary. A report that says one code found may conceal a changed prefix, a missing duplicate or a wrong span. Check the occurrence list and original input together. The G and I cases are particularly useful because a count alone cannot explain their implications: G repeats the same string, while I reveals the limited neighbor class. Both need their context retained for a person deciding whether the rule fits the intended task.

When a result differs from the expectation, preserve the failing example and identify which requirement is disputed. Is the pattern wrong, is the implementation using a different engine or flag, or did somebody silently normalize the input? Change one part at a time and retain the reason. A larger number of matches is not automatically an improvement if it accepts the longer value in D or changes the character policy without an explicit decision.

If you later test an AI-generated extractor, keep that actual output and evaluation separate from these authored expectations. Report the tested inputs, selected rules and observed differences. Passing ten strings would be a narrow result, not certification of a general parser or security filter. A clear handoff says exactly what was checked and what remains outside the exercise, allowing another person to decide which additional cases their real workflow requires.

Questions about extracting reference codes

Does a regex match prove a ticket exists?

No. It establishes a text match under a stated rule. The fictional TK values are not looked up in a ticket system. Existence, ownership, current status and permission to act are separate questions requiring their own evidence and authorization. Keep candidate extraction distinct from a later lookup so that a correct lexical result is not promoted into a business fact it cannot establish.

Should we trim or uppercase the text first?

Only when the intended contract explicitly calls for those transformations. The supplied fixture checks unchanged strings, so lowercase and trailing-newline cases behave differently from a normalized variant. Retain original and transformed values if preprocessing is later adopted. That record helps distinguish what the source contained from what the receiving interface chose to accept after an authorized transformation.

Why does the Greek-letter example still contain a match?

The selected neighbor restriction excludes ASCII letters, digits and underscore only. The Greek letters in case I are outside that class. The result illustrates the stated narrow rule rather than a universal word-boundary definition. If another behavior is required, define the broader character policy and add suitable expectations instead of assuming the current pattern already implements it.

Should repeated code strings be removed?

The occurrence-extraction task preserves them. Case G contains two mentions of the same string, each with its own span. A separate distinct-value view may be useful, but it should not replace occurrence evidence silently. Neither the number of mentions nor the number of distinct strings establishes how many real tickets exist or which reference is operationally relevant.

Are the reported spans byte offsets?

No. They are Python string positions with an excluded end, based on the unchanged strings supplied to the check. Byte positions in a particular encoding and positions in a rendered page are different coordinate systems. A downstream consumer needs the same indexing basis before it can use the spans to locate text reliably. The fixture does not test file encoding or cross-language offset conversion.

What do the ten practice cases establish?

They specify and reproduce selected literal matching behavior in Python 3.12 for an invented code family. They are not customer data, observed model outputs, a full parser-conformance suite or a security assessment. Use them to clarify whole-field versus occurrence extraction and expose hidden transformations. Any real integration needs its own input contract, representative cases, system lookups and authority boundaries before operational use.