Source code for energy_data_retrieval.hydro_catalogue.aha_reviewed
"""Apply frozen, manually reviewed AHA aliases as historical observations only."""
import copy
import json
from typing import Any
from energy_data_retrieval.hydro_catalogue.aha_provenance import enrich_provenance
from energy_data_retrieval.pv_catalogue.catalogue import canonical_json
[docs]
def validate_inventory_review(batch: dict[str, Any], inventory: list[dict[str, Any]]) -> None:
"""Check source-row exclusivity and complete frozen partition before any write.
Accepted and held decisions must be disjoint. A source row cannot be assigned
to multiple canonical plants. Older batches without selected_rows retain
their existing row-equality contract.
"""
lookup = {item["row"]: item for item in inventory}
if len(lookup) != len(inventory):
raise ValueError("Duplicate workbook row")
decisions = batch["accepted"] + batch["held"]
selected = [entry["inventory"]["row"] for entry in decisions]
if len(set(selected)) != len(selected):
raise ValueError("Duplicate source row across review decisions")
identities = [entry["record_id"] for entry in batch["accepted"]]
if len(set(identities)) != len(identities):
raise ValueError("Multiple source rows assigned to one canonical identity")
expected = batch.get("partition", {}).get("selected_rows")
if expected is not None and (
len(expected) != len(set(expected)) or set(expected) != set(selected)
):
raise ValueError("Review does not cover the frozen source partition")
for entry in decisions:
item = entry["inventory"]
if item != lookup.get(item["row"]):
raise ValueError("Reviewed source row differs from downloaded workbook")
[docs]
def enrich_reviewed(
existing: dict[str, Any], entry: dict[str, Any], *, source_id: str, now: str
) -> dict[str, Any]:
"""Reject changed identities and shared scopes; never match names automatically.
Capacity disagreements remain historical source observations, with separate
review-ledger quarantines. No scalar rating, status or coordinate is changed.
"""
identity = entry["reviewed_identity"]
required = {
"record_id",
"country_code",
"name",
"latitude",
"longitude",
"historical_capacity_mw",
}
if set(identity) != required or any(existing[k] != identity[k] for k in required):
raise ValueError("Canonical identity changed since manual review")
if (
entry["record_id"] != existing["record_id"]
or entry["decision"] != "historical_provenance_only"
):
raise ValueError("Explicit provenance-only review required")
item = entry["inventory"]
raw = item["raw"]
if raw.get("SharedPlant") or raw.get("SharedPlantSplit"):
raise ValueError("Shared capacity requires a separate scope review")
row = copy.deepcopy(existing)
ext = json.loads(row["extensions_json"])
observation = {**item, "source_id": source_id, "release_year": 2024}
prior = ext.get("aha_historical_inventory")
if prior:
if prior != [observation]:
raise ValueError("Existing AHA evidence requires reconciliation")
return enrich_provenance(row, now=now)
ext["aha_historical_inventory"] = [observation]
row["extensions_json"] = canonical_json(ext)
fs = json.loads(row["field_sources_json"])
fs.setdefault("extensions_json", [])
row["field_sources_json"] = canonical_json(fs)
row["sources"] = sorted(set(row["sources"] + [source_id]))
return enrich_provenance(row, now=now)