src.dackar.RCA.ner.doc_ref_extractor

doc_ref_extractor.py ───────────────────────────────────────────────────────────────────────────── Extract document cross-reference IDs from nuclear plant text (CR, WO, ECA, LER, GL, SOP, etc.).

Plant-specific flexibility ────────────────────────── Every plant uses its own naming conventions. This extractor is driven by a JSON plant profile (see ner/data/plant_profiles/default_plant_profile.json) that enumerates document types, their prefix strings, and their regex patterns.

To adapt to a new plant:

1. Copy default_plant_profile.json → <your-plant-id>_profile.json

2. Add / remove entries in doc_ref_types, adjusting prefixes and patterns.

3. Pass the file path to load_doc_ref_profile() or directly to extract_doc_refs(text, profile_path=...).

The default profile covers the most common US nuclear site conventions:

CR / CAP, WO / PM, ECA / EC / DCN, SOP / OP / MP / SP / EOP / AOP, LER, GL, IN, BUL, OE / SER / IER, NCR / PER / AR.

Output ────── Each extracted reference is a DocRef namedtuple:

doc_type - canonical type string (e.g. “CR”, “WO”, “GL”) label - NER label string (e.g. “doc_ref_cr”) for schema routing raw - original matched text (before normalization) norm - normalized ID (uppercase, collapsed separators)

Attributes

_DEFAULT_PROFILE_PATH

Classes

DocRef

A single extracted document cross-reference.

Functions

load_doc_ref_profile([profile_path])	Load a plant profile JSON file and return the parsed dict.
_compile_profile(profile)	Return list of (doc_type, label, [compiled_patterns]) from profile.
_normalize_doc_ref(raw)	Return a canonical document reference string.
_make_fp_checker(profile)	Return a callable that returns True when a (doc_type, norm) pair is
extract_doc_refs(text, *[, profile_path, profile, ...])	Extract document cross-reference IDs from text.
extract_doc_ref_ids(text, **kwargs)	Convenience wrapper — returns only the normalised ID strings.

Module Contents

src.dackar.RCA.ner.doc_ref_extractor._DEFAULT_PROFILE_PATH

class src.dackar.RCA.ner.doc_ref_extractor.DocRef

Bases: NamedTuple

A single extracted document cross-reference.

doc_type: str

label: str

raw: str

norm: str

src.dackar.RCA.ner.doc_ref_extractor.load_doc_ref_profile(profile_path=None)

Load a plant profile JSON file and return the parsed dict.

Parameters:

profile_path (Optional[str | pathlib.Path]) – Path to the plant profile JSON. When None, the bundled default_plant_profile.json is used.

Returns:

Parsed profile dict.

Raises:

• FileNotFoundError – If profile_path is given but does not exist.

• ValueError – If the file is not valid JSON.

Return type:

Dict

src.dackar.RCA.ner.doc_ref_extractor._compile_profile(profile)

Return list of (doc_type, label, [compiled_patterns]) from profile.

Patterns are compiled case-insensitively.

Parameters:

profile (Dict)

Return type:

List[Tuple[str, str, List[re.Pattern]]]

src.dackar.RCA.ner.doc_ref_extractor._normalize_doc_ref(raw)

Return a canonical document reference string.

• Uppercase

• Collapse any internal whitespace to a single hyphen

• Collapse multiple consecutive hyphens

• Strip leading/trailing punctuation

Parameters:

raw (str)

Return type:

str

src.dackar.RCA.ner.doc_ref_extractor._make_fp_checker(profile)

Return a callable that returns True when a (doc_type, norm) pair is a false positive and should be dropped.

Parameters:

profile (Dict)

src.dackar.RCA.ner.doc_ref_extractor.extract_doc_refs(text, *, profile_path=None, profile=None, normalize=True, unique=True, max_refs=200)

Extract document cross-reference IDs from text.

Parameters:

• text (str) – Arbitrary chunk or document text.

• profile_path (Optional[str | pathlib.Path]) – Path to a plant profile JSON override. Ignored when profile is supplied directly.

• profile (Optional[Dict]) – Pre-loaded plant profile dict (takes priority over profile_path). Pass this when calling the function many times on the same plant to avoid repeated file I/O.

• normalize (bool) – Normalize matched IDs (uppercase, canonical hyphens).

• unique (bool) – Return each normalised ID at most once.

• max_refs (int) – Safety cap on the number of refs returned.

Returns:

List of DocRef namedtuples in match order.

Return type:

List[DocRef]

src.dackar.RCA.ner.doc_ref_extractor.extract_doc_ref_ids(text, **kwargs)

Convenience wrapper — returns only the normalised ID strings.

Suitable for direct assignment to NERSeed.doc_refs.

Parameters:

• text (str) – Source text.

• **kwargs – Forwarded to extract_doc_refs().

Returns:

List of normalised document reference strings.

Return type:

List[str]