validibot-shared 0.1.0__tar.gz

validibot_shared-0.1.0/.gitignore

@@ -0,0 +1,89 @@
+# Byte-compiled / optimized / DLL files
+**/__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+Desktop.ini
+
+# Temporary files
+tmp/
+
+# Local config that may contain secrets
+.envs/
+
+# AI generated files
+.claude

validibot_shared-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 McQuillen Interactive Pty. Ltd.
+
+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.

validibot_shared-0.1.0/NOTICE

@@ -0,0 +1,23 @@
+Validibot Shared Library
+Copyright (c) 2024-2026 McQuillen Interactive Pty. Ltd.
+
+This product is licensed under the MIT License.
+See the LICENSE file for the full license text.
+
+TRADEMARKS
+
+"Validibot", the Validibot logo, and the Validibot robot character are
+trademarks of McQuillen Interactive Pty. Ltd. The MIT license grants rights
+to the source code only, not to the trademarks.
+
+You may use the Validibot name to accurately describe that your software
+uses or integrates with Validibot, but not in a way that suggests official
+endorsement or affiliation beyond that relationship.
+
+THIRD-PARTY COMPONENTS
+
+This software includes the following third-party components:
+
+- Pydantic (MIT License) - https://docs.pydantic.dev/
+
+Each component is subject to its own license terms.

validibot_shared-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: validibot-shared
+Version: 0.1.0
+Summary: Shared library for data interchange between Validibot and validator containers
+Project-URL: Homepage, https://validibot.com
+Project-URL: Documentation, https://docs.validibot.com
+Project-URL: Repository, https://github.com/danielmcquillen/validibot-shared
+Project-URL: Issues, https://github.com/danielmcquillen/validibot-shared/issues
+Author-email: Daniel McQuillen <daniel@validibot.com>
+Maintainer-email: Daniel McQuillen <daniel@validibot.com>
+License: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: data-interchange,energyplus,fmu,simulation,validation,validibot
+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 :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# validibot-shared
+
+Shared Pydantic models for [Validibot](https://validibot.com) validator containers.
+
+This library defines the data interchange types used between Validibot and its advanced validator services, ensuring type safety and contract consistency.
+
+## Installation
+
+```bash
+pip install validibot-shared
+```
+
+Or with uv:
+
+```bash
+uv add validibot-shared
+```
+
+## Package Structure
+
+```
+validibot_shared/
+├── validations/          # Base validation envelope schemas
+│   └── envelopes.py     # Input/output envelopes for all validators
+├── energyplus/          # EnergyPlus-specific models and envelopes
+│   ├── models.py        # Simulation output models
+│   └── envelopes.py     # Typed envelope subclasses
+└── fmi/                 # FMI/FMU-specific models
+    ├── models.py        # Probe result models
+    └── envelopes.py     # FMI envelope subclasses
+```
+
+## Core Concepts
+
+### Validation Envelopes
+
+The library provides base envelope classes for validator communication:
+
+- `ValidationInputEnvelope` - Standard input format for validation jobs
+- `ValidationOutputEnvelope` - Standard output format with results
+- `ValidationCallback` - Callback payload for async job completion
+
+Supporting classes include `InputFileItem`, `ValidatorInfo`, `ExecutionContext`, `ValidationMessage`, `ValidationMetric`, and `ValidationArtifact`.
+
+### Typed Subclassing Pattern
+
+Domain-specific validators extend the base envelopes with typed fields:
+
+```python
+from validibot_shared.energyplus import EnergyPlusInputEnvelope, EnergyPlusInputs
+
+# The envelope has typed inputs instead of dict[str, Any]
+envelope = EnergyPlusInputEnvelope(
+    run_id="abc-123",
+    inputs=EnergyPlusInputs(timestep_per_hour=4),
+    # ... other fields
+)
+
+# IDE autocomplete and type checking work
+timestep = envelope.inputs.timestep_per_hour
+```
+
+This provides:
+
+- **Type safety** - mypy/pyright catch errors at compile time
+- **Runtime validation** - Pydantic validates all data
+- **IDE support** - Full autocomplete for domain-specific fields
+
+## Usage Examples
+
+### Creating an Input Envelope
+
+```python
+from validibot_shared.energyplus import EnergyPlusInputEnvelope, EnergyPlusInputs
+from validibot_shared.validations.envelopes import (
+    InputFileItem,
+    ValidatorInfo,
+    ExecutionContext,
+)
+
+envelope = EnergyPlusInputEnvelope(
+    run_id="run-123",
+    validator=ValidatorInfo(id="v1", type="energyplus", version="24.2.0"),
+    input_files=[
+        InputFileItem(
+            name="model.idf",
+            mime_type="application/vnd.energyplus.idf",
+            role="primary-model",
+            uri="gs://bucket/model.idf",
+        ),
+    ],
+    inputs=EnergyPlusInputs(timestep_per_hour=4),
+    context=ExecutionContext(
+        callback_url="https://api.example.com/callback",
+        execution_bundle_uri="gs://bucket/run-123/",
+    ),
+)
+```
+
+### Deserializing Results
+
+```python
+from validibot_shared.energyplus import EnergyPlusOutputEnvelope
+
+# Parse JSON response from validator
+envelope = EnergyPlusOutputEnvelope.model_validate_json(response_json)
+
+# Access typed outputs
+if envelope.outputs:
+    print(f"EUI: {envelope.outputs.metrics.eui_kbtu_per_sqft}")
+```
+
+### FMI Probe Results
+
+```python
+from validibot_shared.fmi.models import FMIProbeResult, FMIVariableMeta
+
+# Create a successful probe result
+result = FMIProbeResult.success(
+    variables=[
+        FMIVariableMeta(name="temperature", causality="output", value_type="Real"),
+    ],
+    execution_seconds=0.5,
+)
+
+# Create a failure result
+result = FMIProbeResult.failure(errors=["Invalid FMU: missing modelDescription.xml"])
+```
+
+## Dependencies
+
+- `pydantic>=2.8.0`
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

validibot_shared-0.1.0/README.md

@@ -0,0 +1,136 @@
+# validibot-shared
+
+Shared Pydantic models for [Validibot](https://validibot.com) validator containers.
+
+This library defines the data interchange types used between Validibot and its advanced validator services, ensuring type safety and contract consistency.
+
+## Installation
+
+```bash
+pip install validibot-shared
+```
+
+Or with uv:
+
+```bash
+uv add validibot-shared
+```
+
+## Package Structure
+
+```
+validibot_shared/
+├── validations/          # Base validation envelope schemas
+│   └── envelopes.py     # Input/output envelopes for all validators
+├── energyplus/          # EnergyPlus-specific models and envelopes
+│   ├── models.py        # Simulation output models
+│   └── envelopes.py     # Typed envelope subclasses
+└── fmi/                 # FMI/FMU-specific models
+    ├── models.py        # Probe result models
+    └── envelopes.py     # FMI envelope subclasses
+```
+
+## Core Concepts
+
+### Validation Envelopes
+
+The library provides base envelope classes for validator communication:
+
+- `ValidationInputEnvelope` - Standard input format for validation jobs
+- `ValidationOutputEnvelope` - Standard output format with results
+- `ValidationCallback` - Callback payload for async job completion
+
+Supporting classes include `InputFileItem`, `ValidatorInfo`, `ExecutionContext`, `ValidationMessage`, `ValidationMetric`, and `ValidationArtifact`.
+
+### Typed Subclassing Pattern
+
+Domain-specific validators extend the base envelopes with typed fields:
+
+```python
+from validibot_shared.energyplus import EnergyPlusInputEnvelope, EnergyPlusInputs
+
+# The envelope has typed inputs instead of dict[str, Any]
+envelope = EnergyPlusInputEnvelope(
+    run_id="abc-123",
+    inputs=EnergyPlusInputs(timestep_per_hour=4),
+    # ... other fields
+)
+
+# IDE autocomplete and type checking work
+timestep = envelope.inputs.timestep_per_hour
+```
+
+This provides:
+
+- **Type safety** - mypy/pyright catch errors at compile time
+- **Runtime validation** - Pydantic validates all data
+- **IDE support** - Full autocomplete for domain-specific fields
+
+## Usage Examples
+
+### Creating an Input Envelope
+
+```python
+from validibot_shared.energyplus import EnergyPlusInputEnvelope, EnergyPlusInputs
+from validibot_shared.validations.envelopes import (
+    InputFileItem,
+    ValidatorInfo,
+    ExecutionContext,
+)
+
+envelope = EnergyPlusInputEnvelope(
+    run_id="run-123",
+    validator=ValidatorInfo(id="v1", type="energyplus", version="24.2.0"),
+    input_files=[
+        InputFileItem(
+            name="model.idf",
+            mime_type="application/vnd.energyplus.idf",
+            role="primary-model",
+            uri="gs://bucket/model.idf",
+        ),
+    ],
+    inputs=EnergyPlusInputs(timestep_per_hour=4),
+    context=ExecutionContext(
+        callback_url="https://api.example.com/callback",
+        execution_bundle_uri="gs://bucket/run-123/",
+    ),
+)
+```
+
+### Deserializing Results
+
+```python
+from validibot_shared.energyplus import EnergyPlusOutputEnvelope
+
+# Parse JSON response from validator
+envelope = EnergyPlusOutputEnvelope.model_validate_json(response_json)
+
+# Access typed outputs
+if envelope.outputs:
+    print(f"EUI: {envelope.outputs.metrics.eui_kbtu_per_sqft}")
+```
+
+### FMI Probe Results
+
+```python
+from validibot_shared.fmi.models import FMIProbeResult, FMIVariableMeta
+
+# Create a successful probe result
+result = FMIProbeResult.success(
+    variables=[
+        FMIVariableMeta(name="temperature", causality="output", value_type="Real"),
+    ],
+    execution_seconds=0.5,
+)
+
+# Create a failure result
+result = FMIProbeResult.failure(errors=["Invalid FMU: missing modelDescription.xml"])
+```
+
+## Dependencies
+
+- `pydantic>=2.8.0`
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

validibot_shared-0.1.0/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "validibot-shared"
+version = "0.1.0"
+description = "Shared library for data interchange between Validibot and validator containers"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Daniel McQuillen", email = "daniel@validibot.com" }]
+maintainers = [{ name = "Daniel McQuillen", email = "daniel@validibot.com" }]
+requires-python = ">=3.10"
+keywords = [
+    "validibot",
+    "validation",
+    "energyplus",
+    "fmu",
+    "simulation",
+    "data-interchange",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "pydantic>=2.8.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "ruff>=0.8.0",
+]
+
+[project.urls]
+Homepage = "https://validibot.com"
+Documentation = "https://docs.validibot.com"
+Repository = "https://github.com/danielmcquillen/validibot-shared"
+Issues = "https://github.com/danielmcquillen/validibot-shared/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["validibot_shared"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/validibot_shared",
+    "/tests",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # Pyflakes
+    "I",  # isort
+    "B",  # flake8-bugbear
+    "C4", # flake8-comprehensions
+    "UP", # pyupgrade
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["validibot_shared"]
+
+[tool.pytest.ini_options]
+addopts = "-ra -q"
+testpaths = ["tests"]

validibot_shared-0.1.0/tests/test_energyplus_envelopes.py

@@ -0,0 +1,146 @@
+from pathlib import Path
+
+import pytest
+from pydantic import ValidationError
+
+from validibot_shared.energyplus.envelopes import (
+    EnergyPlusInputEnvelope,
+    EnergyPlusInputs,
+    EnergyPlusOutputEnvelope,
+    EnergyPlusOutputs,
+)
+from validibot_shared.validations.envelopes import (
+    ExecutionContext,
+    InputFileItem,
+    SupportedMimeType,
+    ValidationStatus,
+    ValidatorType,
+)
+
+# Test constants to avoid magic values
+DEFAULT_TIMESTEP_PER_HOUR = 4
+TEST_TIMESTEP_PER_HOUR = 6
+TEST_ELECTRICITY_KWH = 123.4
+TEST_EXECUTION_SECONDS = 12.5
+TEST_EUI_KWH_M2 = 10.5
+
+
+def _base_input_envelope_kwargs():
+    return {
+        "run_id": "run-1",
+        "validator": {
+            "id": "val-1",
+            "type": ValidatorType.ENERGYPLUS,
+            "version": "1.0",
+        },
+        "org": {"id": "org-1", "name": "ValidiBot"},
+        "workflow": {"id": "wf-1", "step_id": "step-1", "step_name": "EnergyPlus"},
+        "input_files": [
+            InputFileItem(
+                name="model.idf",
+                mime_type=SupportedMimeType.ENERGYPLUS_IDF,
+                role="primary-model",
+                uri="gs://bucket/model.idf",
+            )
+        ],
+        "context": ExecutionContext(
+            callback_url="https://example.com/callback",
+            execution_bundle_uri="gs://bucket/run-1/",
+            timeout_seconds=600,
+            tags=["smoke"],
+        ),
+    }
+
+
+def test_energyplus_inputs_defaults():
+    """EnergyPlusInputs should have sensible defaults."""
+    inputs = EnergyPlusInputs()
+
+    assert inputs.timestep_per_hour == DEFAULT_TIMESTEP_PER_HOUR
+    assert inputs.run_period_days is None
+    assert inputs.invocation_mode == "cli"
+
+
+def test_energyplus_inputs_validation():
+    """EnergyPlusInputs should reject invalid values."""
+    with pytest.raises(ValidationError):
+        EnergyPlusInputs(timestep_per_hour=0)
+
+    with pytest.raises(ValidationError):
+        EnergyPlusInputs(invocation_mode="invalid-mode")
+
+
+def test_energyplus_input_envelope_uses_typed_inputs():
+    """EnergyPlusInputEnvelope should parse inputs into EnergyPlusInputs."""
+    data = _base_input_envelope_kwargs()
+    envelope = EnergyPlusInputEnvelope(
+        **data,
+        inputs={"timestep_per_hour": TEST_TIMESTEP_PER_HOUR},
+    )
+
+    assert isinstance(envelope.inputs, EnergyPlusInputs)
+    assert envelope.inputs.timestep_per_hour == TEST_TIMESTEP_PER_HOUR
+
+
+def test_energyplus_input_envelope_rejects_invalid_inputs():
+    """EnergyPlusInputEnvelope should reject invalid input configurations."""
+    data = _base_input_envelope_kwargs()
+
+    with pytest.raises(ValidationError):
+        EnergyPlusInputEnvelope(
+            **data,
+            inputs={"timestep_per_hour": 1, "invocation_mode": "bad"},
+        )
+
+
+def test_energyplus_outputs_compose_nested_models():
+    """EnergyPlusOutputs should compose nested models correctly."""
+    outputs = EnergyPlusOutputs(
+        outputs={"eplusout_sql": "outputs/eplusout.sql", "eplusout_err": None},
+        metrics={"site_electricity_kwh": TEST_ELECTRICITY_KWH},
+        logs={"stdout_tail": "log tail"},
+        energyplus_returncode=0,
+        execution_seconds=TEST_EXECUTION_SECONDS,
+        invocation_mode="python_api",
+    )
+
+    assert isinstance(outputs.outputs.eplusout_sql, Path)
+    assert outputs.metrics.site_electricity_kwh == TEST_ELECTRICITY_KWH
+    assert outputs.logs.stdout_tail == "log tail"
+    assert outputs.execution_seconds == TEST_EXECUTION_SECONDS
+
+
+def test_energyplus_outputs_forbid_extra_fields():
+    """EnergyPlusOutputs should forbid extra fields."""
+    with pytest.raises(ValidationError):
+        EnergyPlusOutputs(
+            energyplus_returncode=0,
+            execution_seconds=1.0,
+            invocation_mode="cli",
+            unknown="nope",
+        )
+
+
+def test_energyplus_output_envelope_accepts_typed_outputs():
+    """EnergyPlusOutputEnvelope should accept typed outputs."""
+    envelope = EnergyPlusOutputEnvelope(
+        run_id="run-2",
+        validator={
+            "id": "val-1",
+            "type": ValidatorType.ENERGYPLUS,
+            "version": "1.0",
+        },
+        status=ValidationStatus.SUCCESS,
+        timing={"queued_at": None, "started_at": None, "finished_at": None},
+        outputs={
+            "outputs": {"eplusout_sql": "outputs/eplusout.sql"},
+            "metrics": {"site_eui_kwh_m2": TEST_EUI_KWH_M2},
+            "energyplus_returncode": 0,
+            "execution_seconds": 3.2,
+            "invocation_mode": "cli",
+        },
+    )
+
+    assert isinstance(envelope.outputs, EnergyPlusOutputs)
+    assert envelope.outputs.outputs.eplusout_sql.name == "eplusout.sql"
+    assert envelope.outputs.metrics.site_eui_kwh_m2 == TEST_EUI_KWH_M2