src.dackar.RCA.adapters.llm_oe_adapter

llm_oe_adapter.py — LLM-backed adapter for fleet and industry OE similar-event queries.

Calls a fine-tuned LLM API that has been trained on INPO SOER, EPRI reports, and NRC LERs (fleet endpoint) or the broader industry database (industry endpoint).

Usage

adapter = LLMOEAdapter(

fleet_url=”https://oe-api.example.com/fleet”, industry_url=”https://oe-api.example.com/industry”, api_key=os.environ[“OE_API_KEY”], timeout_seconds=10.0,

) orchestrator = RCAReasoningOrchestrator(…) orchestrator.set_similar_event_adapter(adapter) result = orchestrator.run(event=…, …)

Error contract

• query() never raises: any transport, decode, or parse failure returns [] and records the reason on the instance.

• degraded and last_error are reset at the start of every query() call, so they always reflect that one call. degraded is set to True when the tier is skipped (no URL configured), the request fails, the response body cannot be decoded, or the response is unusable (wrong shape, or every record malformed). The orchestrator reads degraded after each per-tier call.

• last_error carries the stringified reason for the last degraded call.

Attributes

logger
JsonDict

Classes

LLMOEAdapter

Concrete SimilarEventAdapter backed by a fine-tuned LLM REST API.

Functions

_opt_str(value)	Return str(value) when value is not None, otherwise None.
_str_list(value)	Coerce value to a list of strings; return [] when it is not a list.

Module Contents

src.dackar.RCA.adapters.llm_oe_adapter.logger

src.dackar.RCA.adapters.llm_oe_adapter.JsonDict

src.dackar.RCA.adapters.llm_oe_adapter._opt_str(value)

Return str(value) when value is not None, otherwise None.

Parameters:

value (object)

Return type:

Optional[str]

src.dackar.RCA.adapters.llm_oe_adapter._str_list(value)

Coerce value to a list of strings; return [] when it is not a list.

Parameters:

value (object)

Return type:

List[str]

class src.dackar.RCA.adapters.llm_oe_adapter.LLMOEAdapter(*, fleet_url='', industry_url='', api_key='', timeout_seconds=10.0, max_results=5, model_name='oe-finetuned-v1')

Concrete SimilarEventAdapter backed by a fine-tuned LLM REST API.

The API is expected to accept a POST with a JSON body containing a structured prompt field and return a JSON array of event records (or a dict wrapping that array under events, results, or data).

Parameters:

• fleet_url (str, optional) – Endpoint for the utility-fleet OE database. An empty string means the fleet tier is not configured; querying it marks the tier degraded.

• industry_url (str, optional) – Endpoint for the broad industry OE database (INPO SOER, EPRI, NRC LERs). An empty string means the industry tier is not configured.

• api_key (str, optional) – Bearer token sent as an Authorization header when non-empty.

• timeout_seconds (float, optional) – Default per-request timeout, used when query() is not given an explicit timeout_seconds. Defaults to 10.0.

• max_results (int, optional) – Default maximum number of records to request, used when query() is not given an explicit max_results. Defaults to 5.

• model_name (str, optional) – Fine-tuned model identifier sent in the request payload.

degraded

Whether the most recent query() call failed or was skipped. Reset to False at the start of each call.

Type:

bool

last_error

Stringified reason for the most recent degraded call, or None.

Type:

str or None

fleet_url = ''

industry_url = ''

api_key = ''

timeout_seconds = 10.0

max_results = 5

model_name = 'oe-finetuned-v1'

degraded: bool = False

last_error: str | None = None

query(*, level, asset_id, component_ids, failure_mode_ids, event_type=None, actuation_type=None, max_results=None, timeout_seconds=None)

POST a structured query to the fleet or industry endpoint.

Parameters:

• level ({"fleet", "industry"}) – Which tier to query; selects fleet_url or industry_url and is stamped onto every returned record as source_level.

• asset_id (str or None) – Target asset identifier included in the retrieval prompt.

• component_ids (list of str) – Candidate component identifiers included in the prompt.

• failure_mode_ids (list of str) – Candidate failure-mode identifiers included in the prompt.

• event_type (str, optional) – Event-type hint for the prompt.

• actuation_type (str, optional) – Actuation-type hint for the prompt.

• max_results (int, optional) – Maximum records to request. When None (the default), the instance’s max_results is used.

• timeout_seconds (float, optional) – Per-request timeout. When None (the default), the instance’s timeout_seconds is used.

Returns:

Normalised event records compatible with the similar_event_list.json event-item schema. Returns [] on any failure or when the tier has no configured URL; in those cases degraded is set and last_error records the reason. Each record carries event_id, source_level, confidence_weight (raw match score in [0.0, 1.0], before tier discount), component_id (or None), and the descriptive fields.

Return type:

list of dict

_build_query_prompt(*, level, asset_id, component_ids, failure_mode_ids, event_type, actuation_type, max_results)

Build a structured retrieval prompt for the fine-tuned LLM.

Parameters:

• level (str)

• asset_id (Optional[str])

• component_ids (List[str])

• failure_mode_ids (List[str])

• event_type (Optional[str])

• actuation_type (Optional[str])

• max_results (int)

Return type:

str

static _parse_response(data, *, level)

Normalise the endpoint response into a list of event-record dicts.

Parameters:

• data (object) – The decoded JSON returned by the endpoint. Accepted shapes are a bare list of record dicts, or a dict wrapping such a list under one of the keys events, results, or data.

• level (str) – The tier being queried; stamped onto every record as source_level.

Returns:

One normalised record per usable input record. Individual records that are malformed (not a dict, missing event_id, or carrying a non-numeric / non-finite confidence_weight) are skipped.

Return type:

list of dict

Raises:

ValueError – If data is not a usable shape, or if it carried records but none survived validation. query() catches this, marks the tier degraded, and returns [].