src.dackar.RCA.cap_integration.cap_export_serializer

cap_export_serializer — CAPExportSerializer.

Maps a completed (and analyst-accepted) rca_card + kg_context into a CAPExportPackage conforming to schemas/cap_export_package.json.

Export is gated on an AnalystOverride record (see schemas/analyst_override.json) whose writeback_decision == "accept" — the recommendation flag on the card alone is not treated as proof of acceptance. The resulting export_id is derived from run_id + the override’s override_id so regenerating the package for the same accepted decision is idempotent.

FLOC resolution uses Option B (KG-augmented): component CMMS IDs are stored as optional properties on KG element_usage nodes (maximo_floc / sap_equipment_id) and are returned in kg_context.components[]. No additional KG query is required at export time.

The serializer self-validates its output against schemas/cap_export_package.json and raises on any schema violation (fail-closed); deep validation of the input rca_card / kg_context remains the orchestrator’s responsibility.

Attributes

JsonDict
_OUTPUT_SCHEMA_PATH

Classes

CAPExportSerializer

Serializes an analyst-accepted RCA card into a CAPExportPackage.

Functions

_utcnow_iso()
_output_validator()	Return a cached jsonschema validator for the CAPExportPackage schema.

Module Contents

src.dackar.RCA.cap_integration.cap_export_serializer.JsonDict

src.dackar.RCA.cap_integration.cap_export_serializer._OUTPUT_SCHEMA_PATH

src.dackar.RCA.cap_integration.cap_export_serializer._utcnow_iso()

Return type:

str

src.dackar.RCA.cap_integration.cap_export_serializer._output_validator()

Return a cached jsonschema validator for the CAPExportPackage schema.

class src.dackar.RCA.cap_integration.cap_export_serializer.CAPExportSerializer(config=None)

Serializes an analyst-accepted RCA card into a CAPExportPackage.

Parameters:

• config (Optional[src.dackar.RCA.cap_integration.cap_config.CAPExportConfig]) – CAPExportConfig controlling target system, field maps, and formatting options. Defaults to Maximo with standard mappings.

• Usage:: –

  serializer = CAPExportSerializer(CAPExportConfig(target_system=”maximo”)) modified_card, override_record = orchestrator.apply_override(…) package = serializer.serialize(

  rca_card=modified_card, kg_context=kg_context, run_id=”run-001”, override_record=override_record,

  )

config

_action_type_map

_priority_map

_floc_property = None

_short_desc_limit = 0

serialize(rca_card, kg_context, run_id, override_record)

Build and return a CAPExportPackage dict.

Parameters:

• rca_card (JsonDict) – The analyst-accepted RCA card (post apply_override()).

• kg_context (JsonDict) – The kg_context artifact from the same RCA run. Its asset_id is required, and components[] are used for FLOC/equipment_id resolution via maximo_floc / sap_equipment_id.

• run_id (str) – RCA run identifier.

• override_record (JsonDict) – The AnalystOverride record returned by apply_override(). Must carry writeback_decision == "accept" and an override_id; both gate the export and seed the stable export_id.

Returns:

Conforms to schemas/cap_export_package.json.

Return type:

dict

Raises:

ValueError – If the override record does not represent an accepted writeback, if required identifiers (asset_id / event_id / override_id) are missing or inconsistent across artifacts, if an action_type has no configured mapping, or if the built package fails schema validation.

_assert_override_accepted(override_record)

Verify the override record represents an accepted writeback and return its override_id. This is the authoritative acceptance gate.

Parameters:

override_record (JsonDict)

Return type:

str

_assert_card_approved(rca_card)

Secondary guard: the pipeline must have flagged the card ready.

Parameters:

rca_card (JsonDict)

Return type:

None

_build_floc_index(kg_context)

Build component_id → FLOC/equipment_id lookup from kg_context.components[].

Returns a dict where a value of None means the KG property was absent.

Parameters:

kg_context (JsonDict)

Return type:

Dict[str, Optional[str]]

_serialize_action(action, export_id, rca_card, run_id, floc_index)

Returns (cr_record_dict, unresolved_location_token_or_None).

Parameters:

• action (JsonDict)

• export_id (str)

• rca_card (JsonDict)

• run_id (str)

• floc_index (Dict[str, Optional[str]])

Return type:

tuple

_build_short_description(description, run_id, action_id)

Build a short description guaranteed to be <= short_description_limit.

When enabled, a stable "[RCA:{run_id}] " trace token is prepended; if the token alone would exceed the limit it is truncated so the return value never overflows the CMMS field.

Parameters:

• description (str)

• run_id (str)

• action_id (str)

Return type:

str

_build_long_text(rca_card, run_id, action)

Parameters:

• rca_card (JsonDict)

• run_id (str)

• action (JsonDict)

Return type:

str

_build_maximo_ext()

Return type:

JsonDict

_build_sap_ext()

Return type:

JsonDict

_validate_output(package)

Validate package against schemas/cap_export_package.json (fail-closed).

Raises ValueError with the first offending JSON path and message when the built package does not conform.

Parameters:

package (JsonDict)

Return type:

None