validibot-shared 0.4.0__tar.gz → 0.4.3__tar.gz

{validibot_shared-0.4.0 → validibot_shared-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: validibot-shared
-Version: 0.4.0
+Version: 0.4.3
 Summary: Shared library for data interchange between Validibot and validator containers
 Project-URL: Homepage, https://validibot.com
 Project-URL: Documentation, https://docs.validibot.com
@@ -24,10 +24,10 @@ 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
+Requires-Dist: pydantic==2.13.1
 Provides-Extra: dev
-Requires-Dist: pytest>=8.3.0; extra == 'dev'
-Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Requires-Dist: pytest==9.0.2; extra == 'dev'
+Requires-Dist: ruff==0.14.8; extra == 'dev'
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -50,7 +50,7 @@ Description-Content-Type: text/markdown
 ---
 
 > [!NOTE]
-> This library is part of the [Validibot](https://github.com/danielmcquillen/validibot) open-source data validation platform. It defines the data interchange contract between the core platform and advanced validator containers.
+> This library is part of the [Validibot](https://github.com/danielmcquillen/validibot) open-source data validation platform. It defines the data interchange contract between the core platform and validator backends.
 
 ---
 
@@ -60,21 +60,23 @@ Description-Content-Type: text/markdown
 |------------|-------------|
 | **[validibot](https://github.com/danielmcquillen/validibot)** | Core platform — web UI, REST API, workflow engine |
 | **[validibot-cli](https://github.com/danielmcquillen/validibot-cli)** | Command-line interface |
-| **[validibot-validators](https://github.com/danielmcquillen/validibot-validators)** | Advanced validator containers (EnergyPlus™, FMU) |
+| **[validibot-validator-backends](https://github.com/danielmcquillen/validibot-validator-backends)** | Validator backends for advanced validators (EnergyPlus™, FMU) |
 | **[validibot-shared](https://github.com/danielmcquillen/validibot-shared)** (this repo) | Shared Pydantic models for data interchange |
 
 ---
 
 ## What is Validibot Shared?
 
-Validibot Shared provides the Pydantic models that define how the Validibot core platform communicates with advanced validator containers. When Validibot needs to run a complex validation (like an EnergyPlus™ simulation or FMU probe), it:
+Validibot Shared provides the Pydantic models that define how the Validibot core platform communicates with validator backends. When Validibot needs to run a complex validation (like an EnergyPlus™ simulation or FMU probe), it:
 
 1. **Creates an input envelope** containing the files to validate and configuration
-2. **Launches a validator container** with the envelope as input
+2. **Launches a validator backend** with the envelope as input
 3. **Receives an output envelope** with validation results, metrics, and artifacts
 
 This library ensures both sides speak the same language with full type safety and runtime validation.
 
+Terminology note: in the core `validibot` codebase, `AdvancedValidator` is the Django-side validator class that prepares and launches external work. A validator backend, or future `ValidatorBackend` protocol, is the external implementation it delegates to, usually a container or cloud job. This package defines the envelope boundary between that trusted Django-side validator and the external validator backend. The backend does not receive the full Django submission, workflow, permissions, billing, or credential state unless the parent validator intentionally includes specific data in the envelope.
+
 ## Features
 
 - **Type-safe envelopes** — Pydantic models with full IDE autocomplete and type checking
@@ -85,7 +87,7 @@ This library ensures both sides speak the same language with full type safety an
 ## Disclaimer
 
 > [!NOTE]
-> This library defines data interchange models only — it does not process, store, or transmit user data. However, the models are used by validator containers that execute user-supplied files. See the [LICENSE](LICENSE) for full warranty disclaimer. The authors accept no liability for the behaviour of systems built using these models.
+> This library defines data interchange models only — it does not process, store, or transmit user data. However, the models are used by validator backends that execute user-supplied files. See the [LICENSE](LICENSE) for full warranty disclaimer. The authors accept no liability for the behaviour of systems built using these models.
 
 ## Installation
 
@@ -212,18 +214,32 @@ validibot_shared/
 ```python
 from validibot_shared.energyplus import EnergyPlusInputEnvelope, EnergyPlusInputs
 from validibot_shared.validations.envelopes import (
+    ExecutionContext,
     InputFileItem,
+    OrganizationInfo,
+    SupportedMimeType,
     ValidatorInfo,
-    ExecutionContext,
+    ValidatorType,
+    WorkflowInfo,
 )
 
 envelope = EnergyPlusInputEnvelope(
     run_id="run-123",
-    validator=ValidatorInfo(id="v1", type="energyplus", version="24.2.0"),
+    validator=ValidatorInfo(
+        id="v1",
+        type=ValidatorType.ENERGYPLUS,
+        version="24.2.0",
+    ),
+    org=OrganizationInfo(id="org-123", name="Example Org"),
+    workflow=WorkflowInfo(
+        id="workflow-456",
+        step_id="step-789",
+        step_name="EnergyPlus Simulation",
+    ),
     input_files=[
         InputFileItem(
             name="model.idf",
-            mime_type="application/vnd.energyplus.idf",
+            mime_type=SupportedMimeType.ENERGYPLUS_IDF,
             role="primary-model",
             uri="gs://bucket/model.idf",
         ),
@@ -235,7 +251,7 @@ envelope = EnergyPlusInputEnvelope(
     ),
 )
 
-# Serialize to JSON for the validator container
+# Serialize to JSON for the validator backend
 json_payload = envelope.model_dump_json()
 ```
 
@@ -243,15 +259,16 @@ json_payload = envelope.model_dump_json()
 
 ```python
 from validibot_shared.energyplus import EnergyPlusOutputEnvelope
+from validibot_shared.validations.envelopes import ValidationStatus
 
 # Parse JSON response from validator
 envelope = EnergyPlusOutputEnvelope.model_validate_json(response_json)
 
 # Check status
-if envelope.status == "success":
+if envelope.status == ValidationStatus.SUCCESS:
     # Access typed outputs with full autocomplete
     if envelope.outputs and envelope.outputs.metrics:
-        print(f"EUI: {envelope.outputs.metrics.eui_kbtu_per_sqft} kBtu/sqft")
+        print(f"EUI: {envelope.outputs.metrics.site_eui_kwh_m2} kWh/m²")
 
 # Iterate over validation messages
 for message in envelope.messages:
@@ -354,7 +371,7 @@ This library is one component of the Validibot open-source data validation platf
 |------------|-------------|
 | **[validibot](https://github.com/danielmcquillen/validibot)** | Core platform — web UI, REST API, workflow engine |
 | **[validibot-cli](https://github.com/danielmcquillen/validibot-cli)** | Command-line interface |
-| **[validibot-validators](https://github.com/danielmcquillen/validibot-validators)** | Advanced validator containers (EnergyPlus™, FMU) |
+| **[validibot-validator-backends](https://github.com/danielmcquillen/validibot-validator-backends)** | Validator backends for advanced validators (EnergyPlus™, FMU) |
 | **[validibot-shared](https://github.com/danielmcquillen/validibot-shared)** (this repo) | Shared Pydantic models for data interchange |
 
 ### How It Fits Together
@@ -377,13 +394,13 @@ This library is one component of the Validibot open-source data validation platf
                                     │
          ┌──────────────────────────┼──────────────────────────┐
          ▼                          ▼                          ▼
-┌─────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
-│ validibot-cli   │    │ validibot-validators│    │ validibot-shared    │
-│                 │    │                     │    │  (this repo)        │
-│ Terminal access │    │ EnergyPlus™, FMU    │    │                     │
-│ to API          │    │ containers          │    │ Pydantic models     │
-│                 │    │        │            │    │ (shared contract)   │
-└─────────────────┘    └────────┼────────────┘    └─────────────────────┘
+┌─────────────────┐    ┌──────────────────────────────┐    ┌─────────────────────┐
+│ validibot-cli   │    │ validibot-validator-backends │    │ validibot-shared    │
+│                 │    │                              │    │  (this repo)        │
+│ Terminal access │    │ EnergyPlus™, FMU             │    │                     │
+│ to API          │    │ containers                   │    │ Pydantic models     │
+│                 │    │              │               │    │ (shared contract)   │
+└─────────────────┘    └──────────────┼───────────────┘    └─────────────────────┘
                                 │                          ▲
                                 └──────────────────────────┘
                                    validators import shared
@@ -401,13 +418,10 @@ cd validibot-shared
 uv sync --extra dev
 
 # Run tests
-uv run pytest
+uv run python -m pytest
 
 # Run linter
 uv run ruff check .
-
-# Run type checker
-uv run mypy src/
 ```
 
 ## Trademarks

{validibot_shared-0.4.0 → validibot_shared-0.4.3}/README.md

@@ -18,7 +18,7 @@
 ---
 
 > [!NOTE]
-> This library is part of the [Validibot](https://github.com/danielmcquillen/validibot) open-source data validation platform. It defines the data interchange contract between the core platform and advanced validator containers.
+> This library is part of the [Validibot](https://github.com/danielmcquillen/validibot) open-source data validation platform. It defines the data interchange contract between the core platform and validator backends.
 
 ---
 
@@ -28,21 +28,23 @@
 |------------|-------------|
 | **[validibot](https://github.com/danielmcquillen/validibot)** | Core platform — web UI, REST API, workflow engine |
 | **[validibot-cli](https://github.com/danielmcquillen/validibot-cli)** | Command-line interface |
-| **[validibot-validators](https://github.com/danielmcquillen/validibot-validators)** | Advanced validator containers (EnergyPlus™, FMU) |
+| **[validibot-validator-backends](https://github.com/danielmcquillen/validibot-validator-backends)** | Validator backends for advanced validators (EnergyPlus™, FMU) |
 | **[validibot-shared](https://github.com/danielmcquillen/validibot-shared)** (this repo) | Shared Pydantic models for data interchange |
 
 ---
 
 ## What is Validibot Shared?
 
-Validibot Shared provides the Pydantic models that define how the Validibot core platform communicates with advanced validator containers. When Validibot needs to run a complex validation (like an EnergyPlus™ simulation or FMU probe), it:
+Validibot Shared provides the Pydantic models that define how the Validibot core platform communicates with validator backends. When Validibot needs to run a complex validation (like an EnergyPlus™ simulation or FMU probe), it:
 
 1. **Creates an input envelope** containing the files to validate and configuration
-2. **Launches a validator container** with the envelope as input
+2. **Launches a validator backend** with the envelope as input
 3. **Receives an output envelope** with validation results, metrics, and artifacts
 
 This library ensures both sides speak the same language with full type safety and runtime validation.
 
+Terminology note: in the core `validibot` codebase, `AdvancedValidator` is the Django-side validator class that prepares and launches external work. A validator backend, or future `ValidatorBackend` protocol, is the external implementation it delegates to, usually a container or cloud job. This package defines the envelope boundary between that trusted Django-side validator and the external validator backend. The backend does not receive the full Django submission, workflow, permissions, billing, or credential state unless the parent validator intentionally includes specific data in the envelope.
+
 ## Features
 
 - **Type-safe envelopes** — Pydantic models with full IDE autocomplete and type checking
@@ -53,7 +55,7 @@ This library ensures both sides speak the same language with full type safety an
 ## Disclaimer
 
 > [!NOTE]
-> This library defines data interchange models only — it does not process, store, or transmit user data. However, the models are used by validator containers that execute user-supplied files. See the [LICENSE](LICENSE) for full warranty disclaimer. The authors accept no liability for the behaviour of systems built using these models.
+> This library defines data interchange models only — it does not process, store, or transmit user data. However, the models are used by validator backends that execute user-supplied files. See the [LICENSE](LICENSE) for full warranty disclaimer. The authors accept no liability for the behaviour of systems built using these models.
 
 ## Installation
 
@@ -180,18 +182,32 @@ validibot_shared/
 ```python
 from validibot_shared.energyplus import EnergyPlusInputEnvelope, EnergyPlusInputs
 from validibot_shared.validations.envelopes import (
+    ExecutionContext,
     InputFileItem,
+    OrganizationInfo,
+    SupportedMimeType,
     ValidatorInfo,
-    ExecutionContext,
+    ValidatorType,
+    WorkflowInfo,
 )
 
 envelope = EnergyPlusInputEnvelope(
     run_id="run-123",
-    validator=ValidatorInfo(id="v1", type="energyplus", version="24.2.0"),
+    validator=ValidatorInfo(
+        id="v1",
+        type=ValidatorType.ENERGYPLUS,
+        version="24.2.0",
+    ),
+    org=OrganizationInfo(id="org-123", name="Example Org"),
+    workflow=WorkflowInfo(
+        id="workflow-456",
+        step_id="step-789",
+        step_name="EnergyPlus Simulation",
+    ),
     input_files=[
         InputFileItem(
             name="model.idf",
-            mime_type="application/vnd.energyplus.idf",
+            mime_type=SupportedMimeType.ENERGYPLUS_IDF,
             role="primary-model",
             uri="gs://bucket/model.idf",
         ),
@@ -203,7 +219,7 @@ envelope = EnergyPlusInputEnvelope(
     ),
 )
 
-# Serialize to JSON for the validator container
+# Serialize to JSON for the validator backend
 json_payload = envelope.model_dump_json()
 ```
 
@@ -211,15 +227,16 @@ json_payload = envelope.model_dump_json()
 
 ```python
 from validibot_shared.energyplus import EnergyPlusOutputEnvelope
+from validibot_shared.validations.envelopes import ValidationStatus
 
 # Parse JSON response from validator
 envelope = EnergyPlusOutputEnvelope.model_validate_json(response_json)
 
 # Check status
-if envelope.status == "success":
+if envelope.status == ValidationStatus.SUCCESS:
     # Access typed outputs with full autocomplete
     if envelope.outputs and envelope.outputs.metrics:
-        print(f"EUI: {envelope.outputs.metrics.eui_kbtu_per_sqft} kBtu/sqft")
+        print(f"EUI: {envelope.outputs.metrics.site_eui_kwh_m2} kWh/m²")
 
 # Iterate over validation messages
 for message in envelope.messages:
@@ -322,7 +339,7 @@ This library is one component of the Validibot open-source data validation platf
 |------------|-------------|
 | **[validibot](https://github.com/danielmcquillen/validibot)** | Core platform — web UI, REST API, workflow engine |
 | **[validibot-cli](https://github.com/danielmcquillen/validibot-cli)** | Command-line interface |
-| **[validibot-validators](https://github.com/danielmcquillen/validibot-validators)** | Advanced validator containers (EnergyPlus™, FMU) |
+| **[validibot-validator-backends](https://github.com/danielmcquillen/validibot-validator-backends)** | Validator backends for advanced validators (EnergyPlus™, FMU) |
 | **[validibot-shared](https://github.com/danielmcquillen/validibot-shared)** (this repo) | Shared Pydantic models for data interchange |
 
 ### How It Fits Together
@@ -345,13 +362,13 @@ This library is one component of the Validibot open-source data validation platf
                                     │
          ┌──────────────────────────┼──────────────────────────┐
          ▼                          ▼                          ▼
-┌─────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
-│ validibot-cli   │    │ validibot-validators│    │ validibot-shared    │
-│                 │    │                     │    │  (this repo)        │
-│ Terminal access │    │ EnergyPlus™, FMU    │    │                     │
-│ to API          │    │ containers          │    │ Pydantic models     │
-│                 │    │        │            │    │ (shared contract)   │
-└─────────────────┘    └────────┼────────────┘    └─────────────────────┘
+┌─────────────────┐    ┌──────────────────────────────┐    ┌─────────────────────┐
+│ validibot-cli   │    │ validibot-validator-backends │    │ validibot-shared    │
+│                 │    │                              │    │  (this repo)        │
+│ Terminal access │    │ EnergyPlus™, FMU             │    │                     │
+│ to API          │    │ containers                   │    │ Pydantic models     │
+│                 │    │              │               │    │ (shared contract)   │
+└─────────────────┘    └──────────────┼───────────────┘    └─────────────────────┘
                                 │                          ▲
                                 └──────────────────────────┘
                                    validators import shared
@@ -369,13 +386,10 @@ cd validibot-shared
 uv sync --extra dev
 
 # Run tests
-uv run pytest
+uv run python -m pytest
 
 # Run linter
 uv run ruff check .
-
-# Run type checker
-uv run mypy src/
 ```
 
 ## Trademarks

{validibot_shared-0.4.0 → validibot_shared-0.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "validibot-shared"
-version = "0.4.0"
+version = "0.4.3"
 description = "Shared library for data interchange between Validibot and validator containers"
 readme = "README.md"
 license = { text = "MIT" }
@@ -32,10 +32,10 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Scientific/Engineering",
 ]
-dependencies = ["pydantic>=2.8.0"]
+dependencies = ["pydantic==2.13.1"]
 
 [project.optional-dependencies]
-dev = ["pytest>=8.3.0", "ruff>=0.8.0"]
+dev = ["pytest==9.0.2", "ruff==0.14.8"]
 
 [project.urls]
 Homepage = "https://validibot.com"

{validibot_shared-0.4.0 → validibot_shared-0.4.3}/validibot_shared/validations/envelopes.py

@@ -1,13 +1,17 @@
 """
-Pydantic schemas for Advanced validator job execution envelopes.
+Pydantic schemas for validator backend execution envelopes.
 
-These schemas define the contract between Django and Advanced validator
-containers/services. Advanced validators are validations that run in separate
-containers or remote services (e.g., EnergyPlus, FMU), as opposed to Simple
-validators that run directly within Django.
+These schemas define the contract between Django-side advanced validators and
+external validator backends. In the core ``validibot`` codebase,
+``AdvancedValidator`` is the trusted Django-side class that prepares the run,
+builds the envelope, launches external work through an execution backend, and
+processes the output. A validator backend, or future ``ValidatorBackend``
+protocol, is the external implementation it delegates to, usually a container
+or cloud job. The backend receives only this envelope boundary, not the full
+Django submission, workflow, permissions, or billing state.
 
-This library is used by both the Django app and Advanced validator services to ensure
-type safety and contract consistency across the network boundary.
+This library is used by both the Django app and validator backends
+to ensure type safety and contract consistency across the execution boundary.
 
 ## Deployment Modes
 
@@ -22,11 +26,11 @@ actual storage handling is done by the validators' storage_client module.
 ## Architecture Overview
 
 This module provides a type-safe interface for communication between the Django
-app and Advanced validator containers:
+app and validator backends:
 
 **GCP Mode (async with callbacks):**
 1. Django creates input.json with files, config, callback URL
-2. Django uploads to GCS and triggers validator container
+2. Django uploads to GCS and triggers validator backend runtime
 3. Validator downloads inputs, runs validation, uploads outputs
 4. Validator POSTs minimal callback to Django when complete
 5. Django receives callback and loads full output.json from GCS
@@ -93,7 +97,7 @@ Django deserializes using the correct subclass based on validator.type.
 
 ## Why ValidationCallback?
 
-The callback is a minimal async notification sent from the validator container
+The callback is a minimal async notification sent from the validator backend
 back to the Django app when work completes. It contains only:
 - run_id: Which job finished
 - status: success/failed_validation/failed_runtime/cancelled
@@ -130,7 +134,7 @@ class Severity(str, Enum):
 
 class ValidatorType(str, Enum):
     """
-    Canonical validator types used across Django and validator containers.
+    Canonical validator types used across Django and validator backends.
 
     These values align with Django's ValidationType TextChoices and should be
     used anywhere we serialize validator identifiers in envelopes.
@@ -227,9 +231,9 @@ class ValidatorInfo(BaseModel):
     """
     Information about the validator being executed.
 
-    This identifies which validator container to run and which version.
+    This identifies which validator backend to run and which version.
     The 'type' field determines:
-    1. Which validator container to run (e.g., 'validibot-validator-energyplus')
+    1. Which validator backend to run (e.g., 'validibot-validator-backend-energyplus')
     2. Which envelope subclass Django uses for deserialization
        (EnergyPlusInputEnvelope, FMUInputEnvelope, etc.)
 
@@ -287,7 +291,7 @@ class ExecutionContext(BaseModel):
     """
     Execution context and callback information.
 
-    This provides the validator container with everything it needs to:
+    This provides the validator backend with everything it needs to:
     1. Download input files from storage (execution_bundle_uri)
     2. Upload output files to storage (execution_bundle_uri)
     3. Notify Django when complete (callback_url)
@@ -331,10 +335,10 @@ class ExecutionContext(BaseModel):
 
 class ValidationInputEnvelope(BaseModel):
     """
-    Base input envelope for validator jobs (validibot.input.v1).
+    Base input envelope for validator backend jobs (validibot.input.v1).
 
     This is written to storage as input.json by Django before triggering
-    the validator container.
+    the validator backend.
 
     ## How Subclassing Works
 
@@ -524,9 +528,9 @@ class ValidationTiming(BaseModel):
 
 class ValidationOutputEnvelope(BaseModel):
     """
-    Base output envelope for validator jobs (validibot.output.v1).
+    Base output envelope for validator backend jobs (validibot.output.v1).
 
-    This is written to storage as output.json by the validator container
+    This is written to storage as output.json by the validator backend
     after completion.
 
     ## How Subclassing Works
@@ -622,7 +626,7 @@ class ValidationOutputEnvelope(BaseModel):
 
 class ValidationCallback(BaseModel):
     """
-    Callback payload POSTed from validator container to Django.
+    Callback payload POSTed from validator backend to Django.
 
     Minimal payload to avoid duplication - Django loads the full output.json
     from storage after receiving this callback.