Source code for energy_data_retrieval.wind_catalogue.electrical_tables

"""Review original electrical tables without inferring ratings or compatibility."""

from __future__ import annotations

import hashlib
import math
from typing import Any

from energy_data_retrieval.pv_catalogue.catalogue import canonical_json

from .catalogue import stable_id
from .gppd import evidence_record

REFERENCE_IDS = ("abb_acs800_67_revc_2010", "abb_acs800_67lc_revc_2018")


[docs] def stage_electrical_tables( documents: list[dict[str, Any]], originals: dict[str, bytes], existing: list[dict[str, Any]], *, now: str, ) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]: """Stage complete reviewed model partitions; hold existing identities. Observations retain their units, circuit roles and conditions. No numerical rating is promoted to a scalar, and no application implies turbine fitment. Links identify only explicit assembly/module rows in the same document. """ prior = {(r.get("manufacturer"), r.get("model")) for r in existing} records, ledger = [], [] seen_sources: set[str] = set() seen_models: set[tuple[str, str]] = set() for doc in documents: sid = doc["source_id"] if sid in seen_sources: raise ValueError("Duplicate document") seen_sources.add(sid) if hashlib.sha256(originals[sid]).hexdigest() != doc["sha256"]: raise ValueError("Original document checksum mismatch") rows = doc["rows"] models = [r["model"] for r in rows] if len(models) != len(set(models)) or sorted(models) != sorted(doc["expected_models"]): raise ValueError("Incomplete or duplicate model partition") for item in rows: model = item["model"] if not model or "*" in model or not item["locator"]: raise ValueError("Exact model and locator required") if item["category"] not in {"converter", "control", "lcl_filter", "cooling_fan"}: raise ValueError("Unsupported electrical category") if not item["role"] or not item["application"]: raise ValueError("Circuit role and documented wind application required") for observation in item["observations"]: if not all(observation.get(k) for k in ("role", "conditions", "locator")): raise ValueError("Ratings require role, conditions and locator") for quantity in observation["quantities"]: if not quantity.get("unit") or not quantity.get("quantity"): raise ValueError("Quantity requires a name and original unit") value = quantity["value"] if value is not None and ( isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or value < 0 ): raise ValueError("Invalid electrical quantity") key = (doc["manufacturer"], model) if key in seen_models: raise ValueError("Cross-document model conflict requires review") seen_models.add(key) if key in prior: ledger.append( {"source_id": sid, "model": model, "decision": "existing_identity_review"} ) continue links = [] for link in item.get("links", []): if link["model"] not in models or not link.get("role") or not link.get("locator"): raise ValueError("Application link must be an explicit model in this document") if (doc["manufacturer"], link["model"]) in prior: raise ValueError("Existing linked identity requires revision review") links.append( { **link, "equipment_record_id": stable_id( "equipment", "oem-electrical", doc["manufacturer"], link["model"] ), "source_id": sid, "conditions": ( "Documented internal assembly relation only; " "no turbine compatibility inferred" ), } ) rid = stable_id("equipment", "oem-electrical", *key) records.append( evidence_record( { "record_id": rid, "entity_type": "equipment", "record_scope": "configuration", "name": f"{doc['manufacturer']} {model}", "manufacturer": doc["manufacturer"], "model": model, "equipment_category": item["category"], "variant": doc["revision"], "source_revision": doc["revision"], "capacity_scope": item["role"] + "; electrical ratings are not turbine active power", "compatibility_json": canonical_json(links), "extensions_json": canonical_json( { "electrical_table": item, "document": { k: doc[k] for k in ("source_id", "sha256", "revision", "published_at") }, } ), "notes": "Dated OEM specifications, " "not independently validated performance. " "Unknown scalar power, turbine compatibility and current availability " "remain null. " "AC/DC, active/apparent power, circuit role and duty conditions " "are not interchangeable.", }, source_id=sid, now=now, locator=item["locator"], ) ) ledger.append( { "source_id": sid, "model": model, "record_id": rid, "decision": "addition", "locator": item["locator"], } ) return sorted(records, key=lambda r: r["record_id"]), ledger
[docs] def enrich_electrical_tables( document: dict[str, Any], original: bytes, existing: list[dict[str, Any]], *, now: str ) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]: """Append reviewed specifications to exact existing same-revision equipment. Preserve all previous facts and evidence. A different revision or changed prior enrichment requires conflict review instead of overwriting observations. """ import copy import json if hashlib.sha256(original).hexdigest() != document["sha256"]: raise ValueError("Original document checksum mismatch") models = [item["model"] for item in document["enrichments"]] if len(models) != len(set(models)) or sorted(models) != sorted(document["expected_models"]): raise ValueError("Incomplete or duplicate enrichment partition") rows = copy.deepcopy(existing) ledger = [] for item in document["enrichments"]: if not item.get("locator") or not item.get("specifications"): raise ValueError("Reviewed specifications and locator required") json.dumps(item["specifications"], allow_nan=False) matches = [ r for r in rows if r.get("manufacturer") == document["manufacturer"] and r.get("model") == item["model"] ] if len(matches) != 1: raise ValueError("Enrichment requires one exact existing identity") row = matches[0] if ( row.get("source_revision") != document["revision"] or document["source_id"] not in row["sources"] ): raise ValueError("Different revision/source requires conflict review") extension = json.loads(row.get("extensions_json") or "{}") observation = { **item, "source_id": document["source_id"], "sha256": document["sha256"], "revision": document["revision"], } partition = document.get("partition_id") if partition is not None and (not isinstance(partition, str) or not partition.strip()): raise ValueError("Nonempty specification partition identifier required") partitions = extension.setdefault("specification_partitions", {}) if partition else None previous = ( partitions.get(partition) if partitions is not None else extension.get("qualified_specifications") ) if previous is not None: if previous != observation: raise ValueError("Existing specification conflict requires review") ledger.append({"record_id": row["record_id"], "decision": "unchanged"}) continue if partitions is not None: partitions[partition] = observation else: extension["qualified_specifications"] = observation value = canonical_json(extension) evidence = json.loads(row["evidence_json"]) previous_evidence = evidence.get("extensions_json") evidence["extensions_json"] = { "original_value": value, "unit": None, "normalization": "Append dated qualified OEM facts; prior facts retained", "confidence": "high", "locator": item["locator"], "prior_observations": [previous_evidence] if previous_evidence else [], } row.update( extensions_json=value, evidence_json=canonical_json(evidence), updated_at=now, last_verified_at=now, ) ledger.append( { "record_id": row["record_id"], "model": row["model"], "decision": "enrichment", "locator": item["locator"], } ) return rows, ledger