src.dackar.RCA.cmms_integration.cmms_adapter
============================================

.. py:module:: src.dackar.RCA.cmms_integration.cmms_adapter

.. autoapi-nested-parse::

   cmms_adapter — CMMSContextAdapter Protocol, NoOpCMMSAdapter, MockCMMSAdapter.

   Concrete live adapters (MaximoCMMSAdapter, SAPPMCMMSAdapter) live in
   separate files and implement the same Protocol.
   See CMMS_INTEGRATION_GUIDE.md for the implementation skeleton.



Attributes
----------

.. autoapisummary::

   src.dackar.RCA.cmms_integration.cmms_adapter.JsonDict
   src.dackar.RCA.cmms_integration.cmms_adapter._STATUS_OPEN
   src.dackar.RCA.cmms_integration.cmms_adapter._STATUS_CLOSED
   src.dackar.RCA.cmms_integration.cmms_adapter._STATUS_CANCELLED


Classes
-------

.. autoapisummary::

   src.dackar.RCA.cmms_integration.cmms_adapter.CMMSContextAdapter
   src.dackar.RCA.cmms_integration.cmms_adapter.NoOpCMMSAdapter
   src.dackar.RCA.cmms_integration.cmms_adapter.MockCMMSAdapter


Functions
---------

.. autoapisummary::

   src.dackar.RCA.cmms_integration.cmms_adapter.normalize_cmms_status


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

.. py:data:: JsonDict

.. py:data:: _STATUS_OPEN

.. py:data:: _STATUS_CLOSED

.. py:data:: _STATUS_CANCELLED

.. py:function:: normalize_cmms_status(raw_status)

   Map a raw CMMS status code to the cmms_context schema enum.

   Recognizes every documented Maximo and SAP PM code plus the already-
   normalized values; any unrecognized or empty value maps to ``"unknown"``
   so the artifact never carries a status outside
   ``schemas/cmms_context.json`` (``status`` enum:
   ``open`` / ``closed`` / ``cancelled`` / ``unknown``).


.. py:class:: CMMSContextAdapter

   Bases: :py:obj:`Protocol`


   Protocol for live CMMS data adapters.

   Implementations must be read-only with respect to the CMMS — no writes.
   Results should be idempotent for the same (asset_id, lookback window)
   inputs: calling fetch() twice with the same arguments must return the
   same records (within CMMS data consistency guarantees).


   .. py:method:: fetch(primary_asset_id, sister_component_ids, lookback_from, lookback_to, event)

      Fetch CR and WO records from the CMMS.

      :param primary_asset_id: Asset ID of the event asset.  Used as the primary query scope.
      :param sister_component_ids: KG component IDs of sister equipment (same_train / adjacent).
                                   These are opaque KG identifiers; a live adapter must resolve them
                                   to CMMS FLOCs / equipment IDs (via the ``maximo_floc`` /
                                   ``sap_equipment_id`` KG properties, the same lookup
                                   ``CAPExportSerializer`` uses) before querying.  This Protocol
                                   passes only the IDs, so an adapter that needs the mapping must be
                                   constructed with its own KG/FLOC resolver (or a site config table).
                                   Threading a schema-shaped query scope (component ID + FLOC +
                                   equipment ID) or a KG resolver through ``fetch()`` itself is a
                                   planned contract enhancement, deferred to the live-adapter /
                                   injection MR — see CMMS_INTEGRATION_GUIDE.md §4.
      :param lookback_from: ISO-8601 UTC timestamp — start of the query window (inclusive).
                            Derived from the last PM date on the primary asset, or the
                            event_time minus the configured fallback window.
      :param lookback_to: ISO-8601 UTC timestamp — end of the query window (inclusive).
                          Typically the event timestamp.
      :param event: The raw event dict, passed for adapter-specific context
                    (e.g., failure mode keywords for full-text search).

      :returns: Must contain at minimum:
                ``{"cr_records": [...], "wo_records": [...]}``
                Each record should include at least: an ID field, ``status``,
                ``short_description``, ``created_date``, and
                ``is_sister_equipment``.
      :rtype: dict



.. py:class:: NoOpCMMSAdapter

   Silently returns empty CR and WO lists.

   Used in unit tests, CI, and deployments where no CMMS connection is
   available.  Makes no network calls and has no external dependencies.


   .. py:method:: fetch(primary_asset_id, sister_component_ids, lookback_from, lookback_to, event)


.. py:class:: MockCMMSAdapter(cr_records = None, wo_records = None, filter_by_asset = False)

   Returns configurable fixture CR and WO records.

   Designed for unit testing ``CMMSContextBuilder`` and the synthesizer
   prompt without a live CMMS connection.

   :param cr_records: List of CR record dicts to return from ``fetch()``.
                      Each dict should follow the ``cmms_context.json`` schema
                      ``cr_records`` item structure (minus derived fields that
                      ``CMMSContextBuilder`` computes: ``days_before_event``,
                      ``component_id``).
   :param wo_records: List of WO record dicts to return from ``fetch()``.
   :param filter_by_asset: If ``True``, only records whose ``functional_location`` or
                           ``equipment_id`` contains ``primary_asset_id`` (case-insensitive
                           substring) are returned for the primary scope; all others are
                           treated as sister records.  Defaults to ``False`` (all records
                           returned regardless of asset).


   .. py:attribute:: _cr_records
      :value: []



   .. py:attribute:: _wo_records
      :value: []



   .. py:attribute:: _filter_by_asset
      :value: False



   .. py:method:: fetch(primary_asset_id, sister_component_ids, lookback_from, lookback_to, event)


   .. py:method:: _scope(record, primary_asset_id)
      :staticmethod:


      Return a copy of ``record`` with ``is_sister_equipment`` set by a
      case-insensitive substring match of ``primary_asset_id`` against the
      record's ``functional_location`` / ``equipment_id``.