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