src.dackar.RCA.ner.doc_ref_extractor
====================================

.. py:module:: src.dackar.RCA.ner.doc_ref_extractor

.. autoapi-nested-parse::

   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
----------

.. autoapisummary::

   src.dackar.RCA.ner.doc_ref_extractor._DEFAULT_PROFILE_PATH


Classes
-------

.. autoapisummary::

   src.dackar.RCA.ner.doc_ref_extractor.DocRef


Functions
---------

.. autoapisummary::

   src.dackar.RCA.ner.doc_ref_extractor.load_doc_ref_profile
   src.dackar.RCA.ner.doc_ref_extractor._compile_profile
   src.dackar.RCA.ner.doc_ref_extractor._normalize_doc_ref
   src.dackar.RCA.ner.doc_ref_extractor._make_fp_checker
   src.dackar.RCA.ner.doc_ref_extractor.extract_doc_refs
   src.dackar.RCA.ner.doc_ref_extractor.extract_doc_ref_ids


Module Contents
---------------

.. py:data:: _DEFAULT_PROFILE_PATH

.. py:class:: DocRef

   Bases: :py:obj:`NamedTuple`


   A single extracted document cross-reference.


   .. py:attribute:: doc_type
      :type:  str


   .. py:attribute:: label
      :type:  str


   .. py:attribute:: raw
      :type:  str


   .. py:attribute:: norm
      :type:  str


.. py:function:: load_doc_ref_profile(profile_path = None)

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

   :param profile_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.
   :raises ValueError: If the file is not valid JSON.


.. py:function:: _compile_profile(profile)

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

   Patterns are compiled case-insensitively.


.. py:function:: _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


.. py:function:: _make_fp_checker(profile)

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


.. py:function:: extract_doc_refs(text, *, profile_path = None, profile = None, normalize = True, unique = True, max_refs = 200)

   Extract document cross-reference IDs from *text*.

   :param text: Arbitrary chunk or document text.
   :param profile_path: Path to a plant profile JSON override.  Ignored when
                        *profile* is supplied directly.
   :param profile: 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.
   :param normalize: Normalize matched IDs (uppercase, canonical hyphens).
   :param unique: Return each normalised ID at most once.
   :param max_refs: Safety cap on the number of refs returned.

   :returns: List of :class:`DocRef` namedtuples in match order.


.. py:function:: extract_doc_ref_ids(text, **kwargs)

   Convenience wrapper — returns only the normalised ID strings.

   Suitable for direct assignment to ``NERSeed.doc_refs``.

   :param text: Source text.
   :param \*\*kwargs: Forwarded to :func:`extract_doc_refs`.

   :returns: List of normalised document reference strings.