Source code for energy_data_retrieval.bess_oem_catalogue.dyness

"""Stage the reviewed 2025 Dyness STACK100 manual's explicit configurations.

This offline parser accepts Poppler ``pdftotext -layout`` output for the printed
V2 (2025-03-07) table only. It produces factual candidates, not canonical records.
No option combinations, power, usable energy or current availability are inferred.
A changed edition/layout must receive a separate review before parsing is widened.
"""

from __future__ import annotations

import re
from typing import Any

REFERENCE_IDS = ["dyness_stack100_manual_20250307"]


def _row(page: str, label: str) -> str:
    match = re.search(rf"^[ \t]*{re.escape(label)}[ \t]+(.+)$", page, re.MULTILINE)
    if match is None:
        raise ValueError(f"Missing or changed STACK100 row: {label}")
    return match.group(1).strip()


[docs] def parse_stack100_manual(text: str) -> list[dict[str, Any]]: """Extract thirteen named strings from the reviewed manual's three table pages. Input is offline layout-preserving text, with form-feed page separators. Output energy is the printed, rounded kWh value with unspecified basis; voltage limits are V DC. Printed page/model locators accompany every candidate. Duplicate, missing, reordered or unexpected columns fail closed. The caller must retain the original PDF checksum and inspect all additional specifications. """ if not re.search(r"\bV2\s+2025\.03\.07\b", text): raise ValueError("Expected printed STACK100 manual revision V2, 2025-03-07") if "Table 2-1 Parameters of the STACK100 system" not in text: raise ValueError("Missing reviewed STACK100 Table 2-1 heading") candidates: list[dict[str, Any]] = [] pages = [p for p in text.split("\f") if "System Modules Serial Number" in p] if len(pages) != 3: raise ValueError("Expected exactly three STACK100 configuration table pages") expected_groups = [list(range(3, 8)), list(range(8, 13)), list(range(13, 16))] for index, (page, expected) in enumerate(zip(pages, expected_groups, strict=True)): if "STACK100 User Manual" not in page: raise ValueError("Unexpected document/table context") header = page.split("Module Voltage/Capacity", 1)[0] models = [int(n) for n in re.findall(r"\b100-(\d+)s\b", header)] if models != expected: raise ValueError("Missing, duplicated, reordered or unexpected model columns") counts_row = _row(page, "System Modules Serial Number") if not re.fullmatch(r"\d+(?:\s+\d+)*", counts_row): raise ValueError("Invalid module-count row") counts = [int(n) for n in counts_row.split()] if counts != models: raise ValueError("Module counts do not match exact model identities") energy_row = _row(page, "System Energy Range") energy_tokens = re.findall(r"(\d+(?:\.\d+)?)\s*kWh", energy_row) voltage_row = _row(page, "Operating Voltage") voltage_tokens = re.findall(r"(\d+(?:\.\d+)?)-(\d+(?:\.\d+)?)V", voltage_row) if len(energy_tokens) != len(models) or len(voltage_tokens) != len(models): raise ValueError("Incomplete energy or voltage columns") if re.sub(r"\d+(?:\.\d+)?\s*kWh", "", energy_row).strip(): raise ValueError("Unexpected energy qualifier or unit") if re.sub(r"\d+(?:\.\d+)?-\d+(?:\.\d+)?V", "", voltage_row).strip(): raise ValueError("Unexpected voltage qualifier or unit") for n, energy, (lower, upper) in zip(models, energy_tokens, voltage_tokens, strict=True): energy_kwh, lower_v, upper_v = float(energy), float(lower), float(upper) if energy_kwh <= 0 or not 0 < lower_v < upper_v: raise ValueError("Invalid energy or ordered operating-voltage limits") candidates.append( { "manufacturer": "Dyness", "model": f"STACK100-{n}s", "module_count": n, "energy_kwh": energy_kwh, "energy_basis": "unspecified", "dc_voltage_min_v": lower_v, "dc_voltage_max_v": upper_v, "document_revision": "Printed V2, 2025-03-07; filename V29", "locator": f"Printed page {index + 7}, Table 2-1, STACK100-{n}s column", "review_required": True, } ) return candidates