validibot-shared 0.1.0__py3-none-any.whl

validibot_shared/__init__.py

@@ -0,0 +1,16 @@
+"""Shared domain models and utilities for Simple Validations."""
+
+from validibot_shared.energyplus.models import (
+    EnergyPlusSimulationLogs,
+    EnergyPlusSimulationMetrics,
+    EnergyPlusSimulationOutputs,
+)
+from validibot_shared.fmi.models import FMIProbeResult, FMIVariableMeta
+
+__all__ = [
+    "EnergyPlusSimulationLogs",
+    "EnergyPlusSimulationMetrics",
+    "EnergyPlusSimulationOutputs",
+    "FMIProbeResult",
+    "FMIVariableMeta",
+]

validibot_shared/energyplus/__init__.py

@@ -0,0 +1,25 @@
+"""EnergyPlus integration models and envelopes."""
+
+# Reusable output models (components used within envelope classes)
+# Typed envelope subclasses for validator containers
+from .envelopes import (
+    EnergyPlusInputEnvelope,
+    EnergyPlusInputs,
+    EnergyPlusOutputEnvelope,
+    EnergyPlusOutputs,
+)
+from .models import (
+    EnergyPlusSimulationLogs,
+    EnergyPlusSimulationMetrics,
+    EnergyPlusSimulationOutputs,
+)
+
+__all__ = [
+    "EnergyPlusInputEnvelope",
+    "EnergyPlusInputs",
+    "EnergyPlusOutputEnvelope",
+    "EnergyPlusOutputs",
+    "EnergyPlusSimulationLogs",
+    "EnergyPlusSimulationMetrics",
+    "EnergyPlusSimulationOutputs",
+]

validibot_shared/energyplus/envelopes.py

@@ -0,0 +1,300 @@
+"""
+EnergyPlus-specific envelope schemas for Advanced validator communication.
+
+EnergyPlus is an Advanced validator - it runs in a separate container/service rather
+than within the Django app. These schemas extend the base validation envelopes with
+EnergyPlus-specific typed inputs and outputs.
+
+## Architecture Pattern
+
+This module demonstrates the envelope subclassing pattern:
+
+1. **Base envelopes** (in validibot_shared.validations.envelopes):
+   - ValidationInputEnvelope has inputs: dict[str, Any]
+   - ValidationOutputEnvelope has outputs: dict[str, Any] | None
+
+2. **Domain-specific envelopes** (this file):
+   - EnergyPlusInputEnvelope has inputs: EnergyPlusInputs (typed override!)
+   - EnergyPlusOutputEnvelope has outputs: EnergyPlusOutputs (typed override!)
+
+This provides type safety while maintaining a consistent interface across
+all Advanced validators.
+
+## Reusing Component Models
+
+The EnergyPlusOutputs class composes existing models from models.py:
+- EnergyPlusSimulationOutputs: File paths (SQL, CSV, ERR, ESO)
+- EnergyPlusSimulationMetrics: Extracted metrics (electricity, gas, EUI)
+- EnergyPlusSimulationLogs: Log tails (stdout, stderr, err file)
+
+This follows DRY principles - we don't duplicate data structures. The models.py
+file contains reusable components that represent EnergyPlus simulation outputs.
+These are composed within the envelope classes to provide type-safe output packaging.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from validibot_shared.energyplus.models import (
+    EnergyPlusSimulationLogs,
+    EnergyPlusSimulationMetrics,
+    EnergyPlusSimulationOutputs,
+    InvocationMode,
+)
+from validibot_shared.validations.envelopes import (
+    ValidationInputEnvelope,
+    ValidationOutputEnvelope,
+)
+
+# ==============================================================================
+# EnergyPlus Input Configuration
+# ==============================================================================
+
+
+class EnergyPlusInputs(BaseModel):
+    """
+    EnergyPlus simulation configuration parameters.
+
+    These are the settings that control how the EnergyPlus simulation runs.
+    Input files (IDF model, EPW weather) are passed separately in the parent
+    envelope's input_files field with roles like 'primary-model' and 'weather'.
+
+    ## Why Separate From Input Files?
+
+    Configuration parameters (this class) are different from input files:
+    - Configuration: How to run the simulation (timesteps, invocation mode, etc.)
+    - Input files: What to run (IDF model, weather data)
+
+    This separation allows:
+    - Type-safe configuration validation
+    - Reusable models with different run settings
+    - Clear distinction between data files and execution parameters
+
+    ## Architecture Design
+
+    This configuration model is separate from input files to maintain clear
+    separation of concerns:
+    - Configuration (this class): How to run the simulation
+    - Input files (in parent envelope): What files to process
+
+    Using a typed Pydantic model provides compile-time type checking and
+    runtime validation of all configuration parameters.
+
+    Note: The validator always returns a fixed set of output signals defined
+    in its catalog. Users don't need to specify which outputs they want -
+    they get all defined signals and write assertions against the ones they
+    care about.
+    """
+
+    # Simulation timestep configuration
+    timestep_per_hour: int = Field(
+        default=4,
+        description="Number of timesteps per hour (e.g., 4 = 15-minute intervals)",
+        ge=1,
+        le=60,
+    )
+
+    # Optional run period override
+    run_period_days: int | None = Field(
+        default=None,
+        description="Optional override for run period length in days",
+    )
+
+    # Invocation method
+    invocation_mode: InvocationMode = Field(
+        default="cli",
+        description="How to invoke EnergyPlus: 'cli' or 'python_api'",
+    )
+
+    model_config = {"extra": "forbid"}
+
+
+# ==============================================================================
+# EnergyPlus Output Data
+# ==============================================================================
+
+
+class EnergyPlusOutputs(BaseModel):
+    """
+    EnergyPlus simulation outputs and execution information.
+
+    This contains detailed, EnergyPlus-specific results from the simulation.
+    It's used as the typed 'outputs' field in EnergyPlusOutputEnvelope.
+
+    ## Why This Class Exists
+
+    The parent envelope (ValidationOutputEnvelope) already has generic fields
+    like messages, metrics, and artifacts. This class adds EnergyPlus-specific
+    execution details that don't fit the generic schema:
+    - Return codes and execution timing
+    - Process logs (stdout, stderr, err file)
+    - Specific file paths (eplusout.sql, eplusout.err, etc.)
+
+    ## Composing Reusable Models (DRY Principle)
+
+    We reuse three models from models.py instead of duplicating their definitions:
+    - EnergyPlusSimulationOutputs: File paths (SQL, CSV, ERR, ESO)
+    - EnergyPlusSimulationMetrics: Extracted metrics (electricity, gas, EUI)
+    - EnergyPlusSimulationLogs: Log tails (stdout, stderr, err file)
+
+    This follows the composition pattern - small, focused models are composed
+    into larger structures.
+
+    ## Why Create This Class?
+
+    The parent envelope (ValidationOutputEnvelope) provides generic validation
+    outputs (messages, metrics, artifacts). This class adds EnergyPlus-specific
+    execution details that don't fit the generic schema:
+    - Process return codes and timing
+    - Detailed file paths and logs
+    - Invocation method tracking
+
+    This separation prevents redundancy:
+    - Generic validation data → parent envelope fields
+    - EnergyPlus execution data → this class
+    """
+
+    # Reuse existing output file tracking from models.py
+    outputs: EnergyPlusSimulationOutputs = Field(
+        default_factory=EnergyPlusSimulationOutputs,
+        description="Paths to EnergyPlus output files (SQL, CSV, ERR, ESO)",
+    )
+
+    # Reuse existing metrics tracking from models.py
+    metrics: EnergyPlusSimulationMetrics = Field(
+        default_factory=EnergyPlusSimulationMetrics,
+        description="Extracted simulation metrics (energy use, etc.)",
+    )
+
+    # Reuse existing log tracking from models.py
+    logs: EnergyPlusSimulationLogs | None = Field(
+        default=None, description="Simulation logs (stdout, stderr, err file tails)"
+    )
+
+    # Execution metadata
+    energyplus_returncode: int = Field(
+        description="EnergyPlus process return code (0 = success)"
+    )
+
+    execution_seconds: float = Field(
+        ge=0, description="Total simulation execution time in seconds"
+    )
+
+    invocation_mode: InvocationMode = Field(
+        description="How EnergyPlus was invoked ('cli' or 'python_api')"
+    )
+
+    model_config = {"extra": "forbid"}
+
+
+# ==============================================================================
+# EnergyPlus-Specific Envelopes
+# ==============================================================================
+
+
+class EnergyPlusInputEnvelope(ValidationInputEnvelope):
+    """
+    EnergyPlus-specific input envelope.
+
+    This is what Django serializes and writes to storage as input.json before
+    triggering an EnergyPlus validator container.
+
+    ## Type-Safe Field Override
+
+    The base ValidationInputEnvelope has:
+    ```python
+    inputs: dict[str, Any] = Field(default_factory=dict)
+    ```
+
+    We override it with a typed version:
+    ```python
+    inputs: EnergyPlusInputs
+    ```
+
+    This gives us:
+    - Compile-time type checking in Django (mypy catches config errors)
+    - Runtime validation (Pydantic validates timesteps, output variables, etc.)
+    - Auto-generated documentation (API docs from Pydantic schema)
+    - IDE autocomplete when building input envelopes
+
+    ## How Data Flows
+
+    1. Django creates this envelope:
+       - input_files: [IDF with role='primary-model', EPW with role='weather']
+       - inputs: EnergyPlusInputs(timestep_per_hour=4)
+       - context: ExecutionContext(callback_url=..., execution_bundle_uri=...)
+
+    2. Django serializes to JSON and uploads to storage as input.json
+
+    3. Validator container downloads input.json and deserializes to this class
+
+    4. Validator container extracts typed configuration from inputs field
+    """
+
+    # Override inputs field with typed EnergyPlus configuration
+    inputs: EnergyPlusInputs
+
+
+class EnergyPlusOutputEnvelope(ValidationOutputEnvelope):
+    """
+    EnergyPlus-specific output envelope.
+
+    This is what the EnergyPlus validator container serializes and writes to
+    storage as output.json after simulation completes.
+
+    ## Type-Safe Field Override
+
+    The base ValidationOutputEnvelope has:
+    ```python
+    outputs: dict[str, Any] | None = Field(default=None)
+    ```
+
+    We override it with a typed version:
+    ```python
+    outputs: EnergyPlusOutputs
+    ```
+
+    This gives us the same benefits as the input envelope (type checking,
+    validation, docs, autocomplete).
+
+    ## Generic vs Domain-Specific Data
+
+    The envelope contains BOTH:
+
+    **Generic fields** (from parent ValidationOutputEnvelope):
+    - messages: ValidationMessage list (errors, warnings - consistent
+      across all validators)
+    - metrics: ValidationMetric list (high-level computed values for UI display)
+    - artifacts: ValidationArtifact list (GCS URIs to important output files)
+    - status: SUCCESS/FAILED_VALIDATION/FAILED_RUNTIME/CANCELLED
+
+    **Domain-specific field** (this class):
+    - outputs: EnergyPlusOutputs (returncode, logs, all file paths, execution time)
+
+    ## Why Both?
+
+    - Generic fields enable consistent UI across all validators
+      (same message format, same metric format)
+    - Domain-specific outputs preserve detailed execution info
+      for debugging and reproduction
+
+    ## How Data Flows
+
+    1. Validator container runs EnergyPlus simulation
+
+    2. Validator container creates this envelope:
+       - status: SUCCESS or FAILED_VALIDATION
+       - messages: [ValidationMessage(severity=ERROR, text="Missing required object")]
+       - metrics: [ValidationMetric(name="electricity_kwh", value=12345, unit="kWh")]
+       - outputs: EnergyPlusOutputs(energyplus_returncode=0, ...)
+
+    3. Validator container serializes to JSON and uploads to storage as output.json
+
+    4. Validator container POSTs minimal callback to Django (run_id, status, result_uri)
+
+    5. Django downloads output.json and deserializes to this class
+    """
+
+    # Override outputs field with typed EnergyPlus results
+    outputs: EnergyPlusOutputs

validibot_shared/energyplus/models.py

@@ -0,0 +1,140 @@
+"""
+Reusable EnergyPlus output models.
+
+These models represent EnergyPlus simulation outputs and are used as components
+within the typed envelope classes (see envelopes.py).
+
+They are kept separate from envelopes to follow the single responsibility principle:
+- These models: What data EnergyPlus produces (files, metrics, logs)
+- Envelope classes: How that data is packaged for Django ↔ validator communication
+"""
+
+from __future__ import annotations
+
+from pathlib import Path  # noqa: TC003
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# Useful constants for log tailing
+STDOUT_TAIL_CHARS = 4000
+LOG_TAIL_LINES = 200
+
+# Type alias for invocation modes
+InvocationMode = Literal["python_api", "cli"]
+
+# Type aliases for non-negative numbers
+NonNegFloat = Annotated[float, Field(ge=0)]
+NonNegInt = Annotated[int, Field(ge=0)]
+
+
+class EnergyPlusSimulationOutputs(BaseModel):
+    """
+    EnergyPlus output file paths.
+
+    Tracks the standard EnergyPlus output files produced by a simulation.
+    Used within EnergyPlusOutputs (in envelopes.py) to preserve file locations.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+    eplusout_sql: Path | None = None
+    eplusout_err: Path | None = None
+    eplusout_csv: Path | None = None
+    eplusout_eso: Path | None = None
+
+
+class EnergyPlusSimulationMetrics(BaseModel):
+    """
+    Extracted EnergyPlus simulation metrics.
+
+    These are the core output signals extracted from EnergyPlus simulation results.
+    Field names here must match the binding_config["key"] values in the EnergyPlus
+    provider catalog (see validibot/validations/providers/energyplus.py).
+
+    The validator extracts these values from the EnergyPlus SQL database
+    (eplusout.sql) and they become available as output signals for assertions.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    # ==========================================================================
+    # Energy Consumption (from EnergyPlus meters)
+    # ==========================================================================
+
+    # Total site electricity consumption
+    site_electricity_kwh: NonNegFloat | None = None
+
+    # Total natural gas consumption
+    site_natural_gas_kwh: NonNegFloat | None = None
+
+    # District cooling energy (if present in model)
+    site_district_cooling_kwh: NonNegFloat | None = None
+
+    # District heating energy (if present in model)
+    site_district_heating_kwh: NonNegFloat | None = None
+
+    # ==========================================================================
+    # Energy Use Intensity
+    # ==========================================================================
+
+    # Site EUI (total energy / floor area)
+    site_eui_kwh_m2: NonNegFloat | None = None
+
+    # ==========================================================================
+    # End-Use Breakdown (all fuels combined)
+    # ==========================================================================
+
+    # Space heating energy
+    heating_energy_kwh: NonNegFloat | None = None
+
+    # Space cooling energy
+    cooling_energy_kwh: NonNegFloat | None = None
+
+    # Interior lighting energy
+    interior_lighting_kwh: NonNegFloat | None = None
+
+    # Fan energy (supply, return, exhaust)
+    fans_energy_kwh: NonNegFloat | None = None
+
+    # Pump energy (chilled water, hot water, condenser)
+    pumps_energy_kwh: NonNegFloat | None = None
+
+    # Domestic hot water energy
+    water_systems_kwh: NonNegFloat | None = None
+
+    # ==========================================================================
+    # Comfort / Performance
+    # ==========================================================================
+
+    # Hours heating setpoint not met
+    unmet_heating_hours: NonNegFloat | None = None
+
+    # Hours cooling setpoint not met
+    unmet_cooling_hours: NonNegFloat | None = None
+
+    # Peak electric demand
+    peak_electric_demand_w: NonNegFloat | None = None
+
+    # ==========================================================================
+    # Building Characteristics (from IDF/SQL)
+    # ==========================================================================
+
+    # Total conditioned floor area
+    floor_area_m2: NonNegFloat | None = None
+
+    # Number of thermal zones
+    zone_count: NonNegInt | None = None
+
+
+class EnergyPlusSimulationLogs(BaseModel):
+    """
+    EnergyPlus execution logs.
+
+    Tails of stdout, stderr, and the eplusout.err file for debugging failed simulations.
+    Tails are used instead of full logs to keep envelope sizes reasonable.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+    stdout_tail: str | None = None
+    stderr_tail: str | None = None
+    err_tail: str | None = None

validibot_shared/fmi/__init__.py

@@ -0,0 +1,6 @@
+from validibot_shared.fmi.models import FMIProbeResult, FMIVariableMeta
+
+__all__ = [
+    "FMIProbeResult",
+    "FMIVariableMeta",
+]

validibot_shared/fmi/envelopes.py

@@ -0,0 +1,190 @@
+"""
+Pydantic envelopes for FMI Advanced validator jobs.
+
+FMI is an Advanced validator - it runs in a separate container/service rather
+than within the Django app. These schemas define the contract between Django
+and the FMI validator container:
+- Input envelope: FMU URI plus resolved input values and simulation config
+- Output envelope: FMI outputs, metrics, messages, and artifacts
+
+Inputs/outputs are keyed by validator catalog slugs. Workflow authors cannot
+remap signals; bindings live on catalog entries (input_binding_path) and
+default to slug-name lookups.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from validibot_shared.validations.envelopes import (
+    ExecutionContext,
+    InputFileItem,
+    SupportedMimeType,
+    ValidationInputEnvelope,
+    ValidationOutputEnvelope,
+    ValidatorType,
+)
+
+
+class FMISimulationConfig(BaseModel):
+    """Simulation configuration for FMI runs."""
+
+    start_time: float = Field(
+        default=0.0,
+        description="Simulation start time (seconds).",
+        ge=0,
+    )
+    stop_time: float = Field(
+        default=1.0,
+        description="Simulation stop time (seconds).",
+        gt=0,
+    )
+    step_size: float = Field(
+        default=0.01,
+        description="Communication step size (seconds).",
+        gt=0,
+    )
+    tolerance: float | None = Field(
+        default=None,
+        description="Solver tolerance, if supported by the FMU.",
+        gt=0,
+    )
+
+
+class FMIInputs(BaseModel):
+    """Resolved inputs plus simulation config, keyed by catalog slugs."""
+
+    input_values: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Input values keyed by catalog slugs.",
+    )
+    simulation: FMISimulationConfig = Field(
+        default_factory=FMISimulationConfig,
+        description="Simulation time/step configuration.",
+    )
+    output_variables: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Catalog slugs to capture as outputs. Empty means all output slugs."
+        ),
+    )
+
+
+class FMIOutputs(BaseModel):
+    """FMI execution results keyed by catalog slugs."""
+
+    output_values: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Output values keyed by catalog slugs.",
+    )
+    fmu_guid: str | None = Field(default=None, description="FMU GUID, if reported.")
+    fmi_version: str | None = Field(default=None, description="FMI version.")
+    model_name: str | None = Field(default=None, description="FMU model name.")
+    execution_seconds: float = Field(
+        description="Wall-clock execution time (seconds).",
+        ge=0,
+    )
+    simulation_time_reached: float = Field(
+        description="Simulation time reached before completion/stop.",
+        ge=0,
+    )
+    fmu_log: str | None = Field(
+        default=None,
+        description="Optional FMU log output.",
+    )
+
+
+class FMIInputEnvelope(ValidationInputEnvelope):
+    """Input envelope for FMI validator containers."""
+
+    inputs: FMIInputs
+
+
+class FMIOutputEnvelope(ValidationOutputEnvelope):
+    """Output envelope from FMI validator containers.
+
+    Note: outputs can be None for failure cases where simulation didn't complete.
+    """
+
+    outputs: FMIOutputs | None = None
+
+
+def build_fmi_input_envelope(
+    *,
+    run_id: str,
+    validator,
+    org_id: str,
+    org_name: str,
+    workflow_id: str,
+    step_id: str,
+    step_name: str | None,
+    fmu_uri: str,
+    input_values: dict[str, Any],
+    callback_url: str,
+    execution_bundle_uri: str,
+    simulation: FMISimulationConfig | None = None,
+    output_variables: list[str] | None = None,
+) -> FMIInputEnvelope:
+    """
+    Build an FMIInputEnvelope from Django validation data.
+
+    Args:
+        run_id: ValidationRun ID
+        validator: Validator-like object (id/type/version attrs)
+        org_id: Organization ID
+        org_name: Organization name
+        workflow_id: Workflow ID
+        step_id: Workflow step ID
+        step_name: Optional step name
+        fmu_uri: FMU storage URI (gs://... or local path in dev)
+        input_values: Resolved inputs keyed by catalog slug
+        callback_url: URL to POST callback
+        execution_bundle_uri: Base URI/path for this run's files
+        simulation: Optional FMISimulationConfig
+        output_variables: Optional list of catalog slugs to capture (empty=all outputs)
+    """
+
+    input_files = [
+        InputFileItem(
+            name="model.fmu",
+            mime_type=SupportedMimeType.FMU,
+            role="fmu",
+            uri=fmu_uri,
+        )
+    ]
+
+    envelope_inputs = FMIInputs(
+        input_values=input_values,
+        simulation=simulation or FMISimulationConfig(),
+        output_variables=output_variables or [],
+    )
+
+    context = ExecutionContext(
+        callback_url=callback_url,
+        execution_bundle_uri=execution_bundle_uri,
+    )
+
+    envelope = FMIInputEnvelope(
+        run_id=run_id,
+        validator={
+            "id": str(validator.id),
+            "type": ValidatorType(validator.validation_type),
+            "version": getattr(validator, "version", "1.0.0"),
+        },
+        org={
+            "id": org_id,
+            "name": org_name,
+        },
+        workflow={
+            "id": workflow_id,
+            "step_id": step_id,
+            "step_name": step_name,
+        },
+        input_files=input_files,
+        inputs=envelope_inputs,
+        context=context,
+    )
+
+    return envelope