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)