Source code for energy_data_retrieval.hydro_catalogue.components

"""Explicit ONS powerhouse relationships without additive capacity inference."""

import copy
import json
from typing import Any
from uuid import UUID, uuid5

from energy_data_retrieval.hydro_catalogue.ons import enrich_dispatch_metadata, wri_id
from energy_data_retrieval.pv_catalogue.catalogue import canonical_json


[docs] def enrich_components( existing: dict[str, Any], entry: dict[str, Any], *, now: str ) -> dict[str, Any]: """Attach reviewed components to a plant; never promote component MW to totals.""" item, review = entry["inventory"], entry["review"] ids = json.loads(existing["external_ids_json"]) names = sorted({u["nom_usina"] for u in item["units"]}) equipment = [u["cod_equipamento"] for u in item["units"]] if ( existing["country_code"] != "BRA" or ids.get("wri_gppd") != wri_id(item["ceg"]) or review.get("record_id") != existing["record_id"] or review.get("canonical_name") != existing["name"] or review.get("ceg") != item["ceg"] or review.get("source_names") != names or review.get("decision") != "reviewed_component_relationships" or not review.get("scope_source_id") or len(names) < 2 or len(equipment) != len(set(equipment)) ): raise ValueError("Component identity/scope review does not match inputs") if ids.get("aneel_ceg", item["ceg"]) != item["ceg"]: raise ValueError("Conflicting CEG") row = copy.deepcopy(existing) ext = json.loads(row["extensions_json"]) observation = {**item, "source_id": entry["source_id"], "retrieved_at": now} if "ons_component_review" in ext: if ext["ons_component_review"] != review or ext["ons_hydro_unit_inventory"] != [ observation ]: raise ValueError("Immutable component evidence changed") return row if "ons_hydro_unit_inventory" in ext: raise ValueError("Existing unit evidence requires conflict review") source_ids = sorted({entry["source_id"], "wri_brazil_identity", review["scope_source_id"]}) ext["ons_component_review"] = review ext["ons_hydro_unit_inventory"] = [observation] ext["ons_components"] = [ { "component_id": str(uuid5(UUID(row["record_id"]), f"ons/{item['ceg']}/{name}")), "parent_record_id": row["record_id"], "name": name, "relationship": "powerhouse_of", "generating_unit_ids": sorted( u["cod_equipamento"] for u in item["units"] if u["nom_usina"] == name ), "source_ids": source_ids, "aggregation_role": "excluded_component_evidence", } for name in names ] ids["aneel_ceg"] = item["ceg"] facts = { "extensions_json": canonical_json(ext), "external_ids_json": canonical_json(ids), "owner_names": sorted( {u["nom_agenteproprietario"] for u in item["units"] if u["nom_agenteproprietario"]} ), "operator_names": sorted( {u["nom_agenteoperador"] for u in item["units"] if u["nom_agenteoperador"]} ), } fs, evidence = json.loads(row["field_sources_json"]), json.loads(row["evidence_json"]) for key, value in facts.items(): if key == "owner_names" and row.get(key): evidence.setdefault( "historical_owner_names", {"original_value": row[key], "sources": fs.get(key, [])} ) row[key] = value fs[key] = sorted(set(fs.get(key, []) + source_ids)) evidence[key] = { "locator": "ONS CSV rows " + ",".join(str(u["_row"]) for u in item["units"]), "confidence": "high", "unit": None, "normalization": ( "Explicit registry/component review; " "components are not aliases or additive plant capacity" ), "original_value": value, } row.update( field_sources_json=canonical_json(fs), evidence_json=canonical_json(evidence), sources=sorted(set(row["sources"] + source_ids)), updated_at=now, last_verified_at=now, ) return enrich_dispatch_metadata(row, now=now)