Source code for energy_data_retrieval.bess_oem_catalogue.bslbatt

"""Stage the reviewed seven-column BSLBATT S205/S314 station tables offline.

Input is local ``pdftotext -layout`` output. No fetching, canonical identity,
power calculation, conflict resolution or automatic import is performed.
"""

from __future__ import annotations

import hashlib
import re
from typing import Any

SOURCE_URLS = {
    "S205": "https://bslbatt.com/wp-content/uploads/2025/05/ESS-GRID-S205-250508.pdf",
    "S314": "https://bslbatt.com/wp-content/uploads/2025/10/ESS-GRID-S314-250508.pdf",
}


[docs] def parse_station_table(content: bytes, *, family: str, source_url: str) -> list[dict[str, Any]]: """Fail closed on changed headers/units, missing rows and ambiguous column scope. The source calls an energy row ``Rate Power(kWh)``. Its original label and units are preserved: this parser never interprets that row as active power. Maximum currents remain observations; S205's conflicting 0.5C claim is flagged. """ if family not in SOURCE_URLS or source_url != SOURCE_URLS[family]: raise ValueError("Expected reviewed family and official source URL") text = content.decode("utf-8-sig") lines = [" ".join(line.split()) for line in text.splitlines()] expected = "ESS-GRID " + " ".join(f"{family}-{i}" for i in range(10, 17)) headers = [line for line in lines if line.startswith("ESS-GRID ") and f"{family}-10" in line] if headers != [expected]: raise ValueError("Expected one exact ordered seven-model header") lines = lines[lines.index(expected) + 1 :] def numbers(label: str, count: int) -> list[float]: matches = [line[len(label) :].strip() for line in lines if line.startswith(label)] if len(matches) != 1: raise ValueError(f"Missing or duplicate row: {label}") tokens = matches[0].split() if len(tokens) != count or any(not re.fullmatch(r"\d+(?:\.\d+)?", t) for t in tokens): raise ValueError(f"Unexpected numeric scope or units: {label}") values = list(map(float, tokens)) if min(values) <= 0: raise ValueError(f"Nonpositive rating: {label}") return values voltage = numbers("Rated Voltage(V)", 7) energy = numbers("Rate Power(kWh)", 7) high = numbers("Charge Upper Voltage(V)", 7) low = numbers("Discharge Lower Voltage(V)", 7) packs = numbers("Number of Series", 7) if packs != list(range(10, 17)): raise ValueError("Unexpected series-pack counts") ah = numbers("Rated Capacity(Ah)", 1)[0] cell_ah = numbers("Cell Model(LFP-3.2V)(Ah)", 1)[0] recommended = numbers("Recommended Current(A)", 1)[0] charge = numbers("Max. Charging Current(A)", 1)[0] discharge = numbers("Max. Discharging Current(A)", 1)[0] if ah != cell_ah or not all(lo < v < hi for lo, v, hi in zip(low, voltage, high, strict=True)): raise ValueError("Inconsistent cell capacity or voltage envelope") rows = [] for i in range(7): rows.append( { "model": f"ESS-GRID {family}-{i + 10}", "family": family, "rated_voltage_v": voltage[i], "rated_capacity_ah": ah, "cell_capacity_ah": cell_ah, "reported_energy_kwh": energy[i], "original_energy_label": "Rate Power(kWh)", "active_power_kw": None, "charge_upper_voltage_v": high[i], "discharge_lower_voltage_v": low[i], "series_pack_count": int(packs[i]), "recommended_current_a": recommended, "reported_max_charge_current_a": charge, "reported_max_discharge_current_a": discharge, "current_review_required": family == "S205", "current_review_reason": ( "Page 1 maximum 0.5C versus page 2 maximum current; " "do not resolve automatically" if family == "S205" else None ), "source_url": source_url, "locator": f"PDF page 2 technical specification, column {family}-{i + 10}", "extracted_text_sha256": hashlib.sha256(content).hexdigest(), } ) return rows