hvac-crossover 0.1.0__tar.gz

hvac_crossover-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Doug Larrick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hvac_crossover-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: hvac-crossover
+Version: 0.1.0
+Summary: Multi-source HVAC efficiency optimizer and thermodynamic crossover coordinator
+Author-email: Doug Larrick <doug@parkercat.org>
+License: MIT
+Project-URL: Homepage, https://github.com/dlarrick/hvac-crossover
+Project-URL: Repository, https://github.com/dlarrick/hvac-crossover
+Project-URL: Issues, https://github.com/dlarrick/hvac-crossover/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# hvac-crossover
+
+**Intelligent multi-source HVAC efficiency optimizer and thermodynamic crossover coordinator.**
+
+[![PyPI version](https://img.shields.io/pypi/v/hvac-crossover.svg)](https://pypi.org/project/hvac-crossover/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+`hvac-crossover` is a pure Python, zero-external-dependency library designed to optimize multi-source climate control (such as hybrid inverter heat pumps paired with condensing hydronic boilers). It solves the physical, economic, and constraint-arbitration challenges of running disparate heating and cooling systems together.
+
+## Key Features
+
+- **Thermodynamic Break-Even ($COP^*$):** Dynamic marginal delivered cost ranking ($/MMBtu) computed from live electric ($P_{\text{elec}}$) and gas ($P_{\text{gas}}$) utility tariffs against manufacturer multi-point performance curves.
+- **Setback Recovery vs. Plateau Maintenance:** Automatically engages high-capacity boilers for large recovery pulls ($\Delta T \ge 3.0^\circ\text{F}$) while handing off steady-state maintenance ($\Delta T \le 1.0^\circ\text{F}$) to modulating heat pumps in their peak efficiency range.
+- **Refrigerant Mode Arbitrator:** Prevents multi-split outdoor units (ODUs) from faulting due to opposing heat/cool calls across shared-refrigerant indoor heads, safely diverting conflicting calls to alternate heat sources.
+- **Hydronic Shared-Zone Arbitration:** Resolves $N:M$ bedroom baseboard couplings (master/slave arbitration) and supports 1:1 smart radiator valves (TRVs).
+- **Boiler Short-Cycling Derating:** Accounts for burner turndown limits and cycling penalties when zone calls drop below minimum boiler firing rates.
+
+## Installation
+
+```bash
+pip install hvac-crossover
+```
+
+## Quick Start
+
+```python
+from hvac_crossover import (
+    ProducerProfileFactory, Space, MiniSplitHead, HydronicEmitter,
+    SystemTopology, TariffSchedule, DualFuelCoordinator, ComfortRange
+)
+
+# 1. Define Equipment Topology
+odu = ProducerProfileFactory.load_from_json(
+    "profiles/producers/mitsubishi/mxz_3c30nahz2.json",
+    producer_id="odu1",
+    name="Mitsubishi 30k ODU"
+)
+boiler = ProducerProfileFactory.load_from_json(
+    "profiles/producers/burnham/alta_150.json",
+    producer_id="alta150",
+    name="Burnham Alta 150"
+)
+
+loft = Space(
+    id="loft",
+    name="3rd Floor Loft",
+    emitters=[
+        MiniSplitHead(id="loft_head", producer_id="odu1", nominal_btu=12000.0),
+        HydronicEmitter(id="loft_baseboard", producer_id="alta150", zone_id="z3"),
+    ],
+)
+
+topology = SystemTopology(producers=[odu, boiler], spaces=[loft])
+coordinator = DualFuelCoordinator(topology)
+
+# 2. Evaluate Live Conditions
+plan = coordinator.evaluate_conditions(
+    outdoor_temp=36.0,
+    tariffs=TariffSchedule(gas_cost_per_therm=1.88, electric_cost_per_kwh=0.25),
+    spaces={
+        "loft": {"current": 66.5, "heat_to": 68.0, "cool_to": 74.0}
+    }
+)
+
+directive = plan.space_directives["loft"]
+print(f"Action: {directive.action.value}")
+print(f"Active Emitter: {directive.active_delivery_unit_id}")
+print(f"Economic Crossover Temp: {plan.diagnostics.economic_crossover_temp}°F")
+```
+
+## Development & Testing
+
+```bash
+git clone https://github.com/dlarrick/hvac-crossover.git
+cd hvac-crossover
+python3 -m unittest discover -s tests
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

hvac_crossover-0.1.0/README.md

@@ -0,0 +1,81 @@
+# hvac-crossover
+
+**Intelligent multi-source HVAC efficiency optimizer and thermodynamic crossover coordinator.**
+
+[![PyPI version](https://img.shields.io/pypi/v/hvac-crossover.svg)](https://pypi.org/project/hvac-crossover/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+`hvac-crossover` is a pure Python, zero-external-dependency library designed to optimize multi-source climate control (such as hybrid inverter heat pumps paired with condensing hydronic boilers). It solves the physical, economic, and constraint-arbitration challenges of running disparate heating and cooling systems together.
+
+## Key Features
+
+- **Thermodynamic Break-Even ($COP^*$):** Dynamic marginal delivered cost ranking ($/MMBtu) computed from live electric ($P_{\text{elec}}$) and gas ($P_{\text{gas}}$) utility tariffs against manufacturer multi-point performance curves.
+- **Setback Recovery vs. Plateau Maintenance:** Automatically engages high-capacity boilers for large recovery pulls ($\Delta T \ge 3.0^\circ\text{F}$) while handing off steady-state maintenance ($\Delta T \le 1.0^\circ\text{F}$) to modulating heat pumps in their peak efficiency range.
+- **Refrigerant Mode Arbitrator:** Prevents multi-split outdoor units (ODUs) from faulting due to opposing heat/cool calls across shared-refrigerant indoor heads, safely diverting conflicting calls to alternate heat sources.
+- **Hydronic Shared-Zone Arbitration:** Resolves $N:M$ bedroom baseboard couplings (master/slave arbitration) and supports 1:1 smart radiator valves (TRVs).
+- **Boiler Short-Cycling Derating:** Accounts for burner turndown limits and cycling penalties when zone calls drop below minimum boiler firing rates.
+
+## Installation
+
+```bash
+pip install hvac-crossover
+```
+
+## Quick Start
+
+```python
+from hvac_crossover import (
+    ProducerProfileFactory, Space, MiniSplitHead, HydronicEmitter,
+    SystemTopology, TariffSchedule, DualFuelCoordinator, ComfortRange
+)
+
+# 1. Define Equipment Topology
+odu = ProducerProfileFactory.load_from_json(
+    "profiles/producers/mitsubishi/mxz_3c30nahz2.json",
+    producer_id="odu1",
+    name="Mitsubishi 30k ODU"
+)
+boiler = ProducerProfileFactory.load_from_json(
+    "profiles/producers/burnham/alta_150.json",
+    producer_id="alta150",
+    name="Burnham Alta 150"
+)
+
+loft = Space(
+    id="loft",
+    name="3rd Floor Loft",
+    emitters=[
+        MiniSplitHead(id="loft_head", producer_id="odu1", nominal_btu=12000.0),
+        HydronicEmitter(id="loft_baseboard", producer_id="alta150", zone_id="z3"),
+    ],
+)
+
+topology = SystemTopology(producers=[odu, boiler], spaces=[loft])
+coordinator = DualFuelCoordinator(topology)
+
+# 2. Evaluate Live Conditions
+plan = coordinator.evaluate_conditions(
+    outdoor_temp=36.0,
+    tariffs=TariffSchedule(gas_cost_per_therm=1.88, electric_cost_per_kwh=0.25),
+    spaces={
+        "loft": {"current": 66.5, "heat_to": 68.0, "cool_to": 74.0}
+    }
+)
+
+directive = plan.space_directives["loft"]
+print(f"Action: {directive.action.value}")
+print(f"Active Emitter: {directive.active_delivery_unit_id}")
+print(f"Economic Crossover Temp: {plan.diagnostics.economic_crossover_temp}°F")
+```
+
+## Development & Testing
+
+```bash
+git clone https://github.com/dlarrick/hvac-crossover.git
+cd hvac-crossover
+python3 -m unittest discover -s tests
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

hvac_crossover-0.1.0/hvac_crossover/__init__.py

@@ -0,0 +1,75 @@
+"""
+hvac_crossover - Multi-Source HVAC Efficiency & Thermodynamic Crossover Optimizer
+Decoupled library for optimizing heat pumps, boilers, multi-split constraints, and micro-zoning.
+"""
+
+from .models import (
+    HvacMode,
+    HvacAction,
+    ProducerType,
+    EmitterType,
+    FuelType,
+    NetMeteringMode,
+    ThermalProfile,
+    SharedBoilerRole,
+    SystemPhase,
+    TariffSchedule,
+    Producer,
+    InverterHeatPumpProducer,
+    ModulatingBoilerProducer,
+    SteamBoilerProducer,
+    ProducerProfileFactory,
+    DeliveryUnit,
+    MiniSplitHead,
+    HydronicEmitter,
+    SmartRadiatorValve,
+    ComfortRange,
+    Space,
+    SpaceCondition,
+    SystemSnapshot,
+    SpaceDirective,
+    ProducerDirective,
+    Diagnostics,
+    DispatchPlan,
+    SystemTopology,
+)
+from .config import CoordinatorConfig
+from .coordinator import DualFuelCoordinator
+from .engines import EconomicsEngine, RecoveryEngine, ArbitratorEngine
+
+__version__ = "0.1.0"
+__all__ = [
+    "CoordinatorConfig",
+    "DualFuelCoordinator",
+    "EconomicsEngine",
+    "RecoveryEngine",
+    "ArbitratorEngine",
+    "HvacMode",
+    "HvacAction",
+    "ProducerType",
+    "EmitterType",
+    "FuelType",
+    "NetMeteringMode",
+    "ThermalProfile",
+    "SharedBoilerRole",
+    "SystemPhase",
+    "TariffSchedule",
+    "Producer",
+    "InverterHeatPumpProducer",
+    "ModulatingBoilerProducer",
+    "SteamBoilerProducer",
+    "ProducerProfileFactory",
+    "DeliveryUnit",
+    "MiniSplitHead",
+    "HydronicEmitter",
+    "SmartRadiatorValve",
+    "ComfortRange",
+    "Space",
+    "SpaceCondition",
+    "SystemSnapshot",
+    "SpaceDirective",
+    "ProducerDirective",
+    "Diagnostics",
+    "DispatchPlan",
+    "SystemTopology",
+]

hvac_crossover-0.1.0/hvac_crossover/config.py

@@ -0,0 +1,26 @@
+"""Coordinator configuration, policies, and operational thresholds."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class CoordinatorConfig:
+    """
+    Configurable policies, thresholds, and safety parameters for the DualFuelCoordinator.
+    """
+    # Thermal Recovery vs Plateau Boundaries
+    recovery_delta_threshold_f: float = 3.0   # Deficit >= 3.0°F -> engage high-capacity boiler recovery
+    plateau_delta_threshold_f: float = 1.0    # Deficit <= 1.0°F -> hand off to heat pump plateau
+
+    # Economic Switching Buffer (Hysteresis)
+    # E.g. 1.05 means heat pump cost ($/MMBtu) must be at least 5% cheaper than boiler
+    # to switch from boiler to heat pump, preventing flip-flopping right at the crossover line.
+    economic_switching_buffer: float = 1.05
+
+    # Absolute Outdoor Temperature Safeguards
+    min_heat_pump_temp_f: float = -13.0       # Minimum rated operational temperature for cold-climate inverters
+
+    # Operational Interlocks
+    passive_ventilation_override: bool = True # Open window/skylight forces space delivery units to OFF
+    enforce_odu_mode_locks: bool = True       # Enforce single-refrigerant mode lock across heads on same ODU
+    short_cycling_protection: bool = True     # Apply burner cycling derate when load is below boiler min fire

hvac_crossover-0.1.0/hvac_crossover/coordinator.py

@@ -0,0 +1,295 @@
+"""Main DualFuelCoordinator facade and central evaluation pipeline."""
+
+from typing import Dict, Any, Optional, List, Set, Tuple
+from .models.enums import HvacMode, HvacAction, SystemPhase, ProducerType
+from .models.topology import SystemTopology
+from .models.tariffs import TariffSchedule
+from .models.snapshot import SystemSnapshot
+from .models.spaces import SpaceCondition, ComfortRange
+from .models.delivery import MiniSplitHead, HydronicEmitter
+from .models.plan import DispatchPlan, SpaceDirective, ProducerDirective, Diagnostics
+from .config import CoordinatorConfig
+from .engines.economics import EconomicsEngine
+from .engines.recovery import RecoveryEngine
+from .engines.arbitrator import ArbitratorEngine
+
+
+class DualFuelCoordinator:
+    """
+    Central coordination service and facade for dual-fuel HVAC systems.
+    Evaluates ground-truth environmental and space conditions to produce
+    actionable hardware directives and explainable telemetry.
+    """
+
+    def __init__(
+        self,
+        topology: SystemTopology,
+        config: Optional[CoordinatorConfig] = None,
+    ):
+        self.topology = topology
+        self.config = config or CoordinatorConfig()
+        self.economics = EconomicsEngine()
+        self.recovery = RecoveryEngine(self.config)
+        self.arbitrator = ArbitratorEngine(self.config)
+
+    def evaluate(self, snapshot: SystemSnapshot) -> DispatchPlan:
+        """
+        Evaluates the ground-truth snapshot and generates a DispatchPlan.
+        """
+        space_directives: Dict[str, SpaceDirective] = {}
+        producer_directives: Dict[str, ProducerDirective] = {}
+        explanations: List[str] = []
+
+        # 1. Determine Macro System Phase
+        system_phase = self.recovery.determine_system_phase(snapshot.spaces, self.topology)
+
+        # 2. Find primary boiler for crossover calculations
+        boiler_producers = [
+            p for p in self.topology.producers
+            if p.producer_type in (ProducerType.MODULATING_BOILER, ProducerType.ATMOSPHERIC_BOILER, ProducerType.STEAM_BOILER)
+        ]
+        primary_boiler = boiler_producers[0] if boiler_producers else None
+
+        # Calculate general economic crossover temp for telemetry
+        crossover_temp = 41.4  # Default fallback
+        hp_producers = [p for p in self.topology.producers if p.producer_type == ProducerType.INVERTER_HEAT_PUMP]
+        if primary_boiler and hp_producers:
+            t_cross = self.economics.compute_crossover_temperature(
+                tariffs=snapshot.tariffs,
+                odu=hp_producers[0],
+                boiler=primary_boiler,
+                telemetry=snapshot.telemetry,
+            )
+            if t_cross is not None:
+                crossover_temp = t_cross
+
+        # 3. Initial Space Demand Assessment
+        candidate_space_modes: Dict[str, HvacMode] = {}
+        candidate_emitters: Dict[str, Optional[str]] = {}
+        target_temps: Dict[str, Optional[float]] = {}
+        requested_boiler_zones: Set[Tuple[str, str]] = set()
+
+        space_costs: Dict[str, float] = {}
+        space_cops: Dict[str, float] = {}
+
+        for space in self.topology.spaces:
+            cond = snapshot.spaces.get(space.id)
+            if not cond:
+                candidate_space_modes[space.id] = HvacMode.OFF
+                candidate_emitters[space.id] = None
+                target_temps[space.id] = None
+                continue
+
+            # Check window interlocks for passive ventilation
+            if cond.window_open and self.config.passive_ventilation_override:
+                candidate_space_modes[space.id] = HvacMode.OFF
+                candidate_emitters[space.id] = None
+                target_temps[space.id] = None
+                explanations.append(f"Space '{space.name}' delivery units turned OFF due to open window/skylight.")
+                continue
+
+            # Deadband / Uncontrolled Float Check
+            if cond.comfort.is_in_deadband(cond.current_temp):
+                candidate_space_modes[space.id] = HvacMode.OFF
+                candidate_emitters[space.id] = None
+                target_temps[space.id] = None
+                continue
+
+            # Cooling Demand
+            if cond.comfort.demands_cool(cond.current_temp):
+                candidate_space_modes[space.id] = HvacMode.COOL
+                target_temps[space.id] = cond.comfort.cool_to
+                cooling_heads = [e for e in space.emitters if isinstance(e, MiniSplitHead)]
+                if cooling_heads:
+                    candidate_emitters[space.id] = cooling_heads[0].id
+                else:
+                    candidate_emitters[space.id] = None
+                continue
+
+            # Heating Demand
+            if cond.comfort.demands_heat(cond.current_temp):
+                candidate_space_modes[space.id] = HvacMode.HEAT
+                target_temps[space.id] = cond.comfort.heat_to
+
+                # Estimate space heating load
+                load_btu = space.estimated_heat_loss_btu_per_hr(cond.current_temp, snapshot.outdoor_temp)
+
+                # Check if space is in heavy setback recovery (>= 3.0°F deficit)
+                in_recovery = self.recovery.is_space_in_recovery(cond)
+
+                # Find available hydronic emitter
+                hydronic_emitters = [e for e in space.emitters if isinstance(e, HydronicEmitter)]
+                mini_split_heads = [e for e in space.emitters if isinstance(e, MiniSplitHead)]
+
+                if in_recovery and hydronic_emitters and snapshot.outdoor_temp < 45.0:
+                    # In deep recovery pull-up below 45°F, dispatch high-capacity boiler
+                    selected = hydronic_emitters[0]
+                    candidate_emitters[space.id] = selected.id
+                    requested_boiler_zones.add((selected.producer_id, selected.zone_id))
+                    explanations.append(
+                        f"Space '{space.name}' in setback recovery (deficit {cond.comfort.heat_deficit(cond.current_temp):.1f}°F): "
+                        f"dispatched high-capacity hydronic boiler for rapid pull-up."
+                    )
+                else:
+                    # Steady-state plateau or mild weather: rank emitters economically
+                    ranked = self.economics.rank_space_emitters_by_cost(
+                        space=space,
+                        outdoor_temp_f=snapshot.outdoor_temp,
+                        tariffs=snapshot.tariffs,
+                        topology=self.topology,
+                        load_btu=load_btu,
+                        telemetry=snapshot.telemetry,
+                        part_load=True,
+                    )
+                    if ranked:
+                        best_emitter, best_cost, best_eff = ranked[0]
+                        candidate_emitters[space.id] = best_emitter.id
+                        space_costs[space.id] = round(best_cost, 2)
+                        space_cops[space.id] = round(best_eff, 2)
+
+                        if isinstance(best_emitter, HydronicEmitter):
+                            requested_boiler_zones.add((best_emitter.producer_id, best_emitter.zone_id))
+
+        # 4. Multi-Split ODU Mode Conflict Arbitration
+        if self.config.enforce_odu_mode_locks:
+            resolved_modes, odu_explanations = self.arbitrator.arbitrate_odu_modes(
+                requested_space_modes=candidate_space_modes,
+                topology=self.topology,
+                space_conditions=snapshot.spaces,
+            )
+            explanations.extend(odu_explanations)
+        else:
+            resolved_modes = candidate_space_modes
+
+        # 5. Shared Hydronic Zone Valve Arbitration
+        approved_boiler_zones, boiler_explanations = self.arbitrator.arbitrate_shared_boiler_zones(
+            requested_boiler_zones=requested_boiler_zones,
+            topology=self.topology,
+            space_conditions=snapshot.spaces,
+        )
+        explanations.extend(boiler_explanations)
+
+        # 6. Build Space Directives
+        for space in self.topology.spaces:
+            cond = snapshot.spaces.get(space.id)
+            final_mode = resolved_modes.get(space.id, HvacMode.OFF)
+            emitter_id = candidate_emitters.get(space.id)
+            target = target_temps.get(space.id)
+
+            if cond and cond.window_open and self.config.passive_ventilation_override:
+                action = HvacAction.PASSIVE_VENTILATION
+                final_mode = HvacMode.OFF
+                emitter_id = None
+            elif final_mode == HvacMode.HEAT:
+                action = HvacAction.HEATING
+            elif final_mode in (HvacMode.COOL, HvacMode.DRY):
+                action = HvacAction.COOLING
+            else:
+                action = HvacAction.IDLE if cond and cond.comfort.is_in_deadband(cond.current_temp) else HvacAction.OFF
+
+            active_producer_id = None
+            if emitter_id:
+                for e in space.emitters:
+                    if e.id == emitter_id:
+                        active_producer_id = e.producer_id
+                        break
+
+            space_directives[space.id] = SpaceDirective(
+                space_id=space.id,
+                action=action,
+                hvac_mode=final_mode,
+                target_temp=target,
+                active_delivery_unit_id=emitter_id,
+                active_producer_id=active_producer_id,
+                explanation=f"Mode: {final_mode.value}, Action: {action.value}"
+            )
+
+        # 7. Build Producer Directives
+        odu_operational_modes: Dict[str, str] = {}
+        for producer in self.topology.producers:
+            if producer.producer_type == ProducerType.INVERTER_HEAT_PUMP:
+                # Find mode of active heads on this ODU
+                active_modes = [
+                    space_directives[s.id].hvac_mode
+                    for s in self.topology.get_spaces_for_producer(producer.id)
+                    if s.id in space_directives and space_directives[s.id].active_producer_id == producer.id
+                ]
+                active_modes = [m for m in active_modes if m != HvacMode.OFF]
+                odu_mode = active_modes[0] if active_modes else HvacMode.OFF
+                is_active = odu_mode != HvacMode.OFF
+                odu_operational_modes[producer.id] = odu_mode.value
+
+                producer_directives[producer.id] = ProducerDirective(
+                    producer_id=producer.id,
+                    operational_mode=odu_mode,
+                    is_active=is_active,
+                )
+            else:
+                # Boiler / Furnace producer
+                active_zones = [
+                    zone_id for b_id, zone_id in approved_boiler_zones
+                    if b_id == producer.id
+                ]
+                is_active = len(active_zones) > 0
+                producer_directives[producer.id] = ProducerDirective(
+                    producer_id=producer.id,
+                    operational_mode=HvacMode.HEAT if is_active else HvacMode.OFF,
+                    is_active=is_active,
+                    active_zones=active_zones,
+                )
+
+        # 8. Assemble Diagnostics
+        diagnostics = Diagnostics(
+            economic_crossover_temp=round(crossover_temp, 1),
+            system_phase=system_phase,
+            odu_modes=odu_operational_modes,
+            space_costs_per_mmbtu=space_costs,
+            space_cops=space_cops,
+            explanations=explanations,
+        )
+
+        return DispatchPlan(
+            space_directives=space_directives,
+            producer_directives=producer_directives,
+            diagnostics=diagnostics,
+        )
+
+    def evaluate_conditions(
+        self,
+        outdoor_temp: float,
+        tariffs: TariffSchedule,
+        spaces: Dict[str, Dict[str, Any]],
+        solar_export_watts: float = 0.0,
+        boiler_return_temp: Optional[float] = None,
+        elec_rate_override: Optional[float] = None,
+        current_hour: Optional[int] = None,
+    ) -> DispatchPlan:
+        """
+        Convenience keyword-argument evaluation method that constructs a SystemSnapshot internally.
+        """
+        space_conditions: Dict[str, SpaceCondition] = {}
+        for s_id, s_data in spaces.items():
+            current_temp = float(s_data["current"])
+            comfort = ComfortRange(
+                heat_to=s_data.get("heat_to"),
+                cool_to=s_data.get("cool_to"),
+            )
+            window_open = bool(s_data.get("window_open", False))
+            occupied = bool(s_data.get("occupied", True))
+            space_conditions[s_id] = SpaceCondition(
+                current_temp=current_temp,
+                comfort=comfort,
+                window_open=window_open,
+                occupied=occupied,
+            )
+
+        snapshot = SystemSnapshot(
+            outdoor_temp=outdoor_temp,
+            tariffs=tariffs,
+            spaces=space_conditions,
+            solar_export_watts=solar_export_watts,
+            boiler_return_temp=boiler_return_temp,
+            elec_rate_override=elec_rate_override,
+            current_hour=current_hour,
+        )
+        return self.evaluate(snapshot)

hvac_crossover-0.1.0/hvac_crossover/engines/__init__.py

@@ -0,0 +1,11 @@
+"""Specialized evaluation engines for hybrid_hvac."""
+
+from .economics import EconomicsEngine
+from .recovery import RecoveryEngine
+from .arbitrator import ArbitratorEngine
+
+__all__ = [
+    "EconomicsEngine",
+    "RecoveryEngine",
+    "ArbitratorEngine",
+]