eb-contracts 0.2.0__py3-none-any.whl

eb_contracts/__init__.py

@@ -0,0 +1,24 @@
+"""
+Public API for EB contracts.
+
+This package provides contract artifacts and validation entrypoints for
+forecasting and panel-based evaluation.
+"""
+
+from __future__ import annotations
+
+from eb_contracts.api.validate import (
+    panel_point_v1,
+    panel_quantile_v1,
+)
+
+######################################
+# Public API
+######################################
+from eb_contracts.contracts._internal.runtime import set_validation_mode
+
+__all__ = [
+    "panel_point_v1",
+    "panel_quantile_v1",
+    "set_validation_mode",
+]

eb_contracts/api/__init__.py

@@ -0,0 +1,27 @@
+"""
+Public migration API.
+
+This package provides explicit helpers for adapting external data into EB
+contract artifacts.
+"""
+
+from __future__ import annotations
+
+######################################
+# Public API
+######################################
+from eb_contracts.api.migrate_forecast import (
+    PanelPointColumns,
+    PanelQuantileColumns,
+    to_panel_point_result_v1,
+    to_panel_point_v1,
+    to_panel_quantile_v1,
+)
+
+__all__ = [
+    "PanelPointColumns",
+    "PanelQuantileColumns",
+    "to_panel_point_result_v1",
+    "to_panel_point_v1",
+    "to_panel_quantile_v1",
+]

eb_contracts/api/migrate_forecast.py

@@ -0,0 +1,122 @@
+"""
+Forecast migration helpers.
+
+This module contains explicit utilities for adapting "in the wild" forecast frames
+into EB contract artifacts.
+
+Migration is intentionally explicit:
+- You provide column mappings.
+- The output is a validated contract artifact (unless validation mode is off).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Final
+
+import pandas as pd
+
+from eb_contracts.contracts.forecast_panel.v1.forecast_panel import (
+    PanelPointForecastV1,
+    PanelQuantileForecastV1,
+)
+from eb_contracts.contracts.results.v1.panel_point_result import PanelPointResultV1
+
+######################################
+# Mapping specs
+######################################
+
+
+@dataclass(frozen=True, slots=True)
+class PanelPointColumns:
+    """Column mapping for point forecasts."""
+
+    entity_id: str
+    interval_start: str
+    y_true: str
+    y_pred: str
+
+
+@dataclass(frozen=True, slots=True)
+class PanelQuantileColumns:
+    """Column mapping for quantile forecasts."""
+
+    entity_id: str
+    interval_start: str
+    y_true: str
+    q: str
+    y_pred_q: str
+
+
+######################################
+# Public API
+######################################
+
+
+_RESULT_COLUMNS: Final[set[str]] = {
+    PanelPointResultV1.Y_TRUE_COL,
+    PanelPointResultV1.Y_PRED_COL,
+}
+
+
+def to_panel_point_v1(frame: pd.DataFrame, *, columns: PanelPointColumns) -> PanelPointForecastV1:
+    """Adapt a frame into the PanelPointForecastV1 contract."""
+    out = frame.rename(
+        columns={
+            columns.entity_id: PanelPointForecastV1.ENTITY_COL,
+            columns.interval_start: PanelPointForecastV1.INTERVAL_START_COL,
+            columns.y_true: PanelPointForecastV1.Y_TRUE_COL,
+            columns.y_pred: PanelPointForecastV1.Y_PRED_COL,
+        }
+    )
+    keep = [
+        PanelPointForecastV1.ENTITY_COL,
+        PanelPointForecastV1.INTERVAL_START_COL,
+        PanelPointForecastV1.Y_TRUE_COL,
+        PanelPointForecastV1.Y_PRED_COL,
+    ]
+    return PanelPointForecastV1.from_frame(out.loc[:, keep])
+
+
+def to_panel_quantile_v1(
+    frame: pd.DataFrame, *, columns: PanelQuantileColumns
+) -> PanelQuantileForecastV1:
+    """Adapt a frame into the PanelQuantileForecastV1 contract."""
+    out = frame.rename(
+        columns={
+            columns.entity_id: PanelQuantileForecastV1.ENTITY_COL,
+            columns.interval_start: PanelQuantileForecastV1.INTERVAL_START_COL,
+            columns.y_true: PanelQuantileForecastV1.Y_TRUE_COL,
+            columns.q: PanelQuantileForecastV1.Q_COL,
+            columns.y_pred_q: PanelQuantileForecastV1.Y_PRED_Q_COL,
+        }
+    )
+    keep = [
+        PanelQuantileForecastV1.ENTITY_COL,
+        PanelQuantileForecastV1.INTERVAL_START_COL,
+        PanelQuantileForecastV1.Y_TRUE_COL,
+        PanelQuantileForecastV1.Q_COL,
+        PanelQuantileForecastV1.Y_PRED_Q_COL,
+    ]
+    return PanelQuantileForecastV1.from_frame(out.loc[:, keep])
+
+
+def to_panel_point_result_v1(
+    frame: pd.DataFrame, *, columns: PanelPointColumns
+) -> PanelPointResultV1:
+    """Adapt a frame into the PanelPointResultV1 contract."""
+    out = frame.rename(
+        columns={
+            columns.entity_id: PanelPointResultV1.ENTITY_COL,
+            columns.interval_start: PanelPointResultV1.INTERVAL_START_COL,
+            columns.y_true: PanelPointResultV1.Y_TRUE_COL,
+            columns.y_pred: PanelPointResultV1.Y_PRED_COL,
+        }
+    )
+    keep = [
+        PanelPointResultV1.ENTITY_COL,
+        PanelPointResultV1.INTERVAL_START_COL,
+        PanelPointResultV1.Y_TRUE_COL,
+        PanelPointResultV1.Y_PRED_COL,
+    ]
+    return PanelPointResultV1.from_frame(out.loc[:, keep])

eb_contracts/api/validate.py

@@ -0,0 +1,81 @@
+"""
+Public validation entrypoints for contract artifacts.
+
+This module defines stable, versioned entrypoints for validating and constructing
+contract-wrapped data artifacts. Consumers should prefer these functions over
+importing versioned contract modules directly.
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from eb_contracts.contracts.costs.v1.cost_asymmetry_spec import CostAsymmetrySpecV1
+from eb_contracts.contracts.demand_panel.v1.panel_demand import (
+    PanelDemandV1,
+    validate_panel_demand_v1,
+)
+from eb_contracts.contracts.forecast_panel.v1.forecast_panel import (
+    PanelPointForecastV1,
+    PanelQuantileForecastV1,
+)
+from eb_contracts.contracts.results.v1.panel_point_result import PanelPointResultV1
+
+######################################
+# Public API
+######################################
+
+
+def panel_demand_v1(panel: PanelDemandV1) -> None:
+    """Validate a V1 demand panel artifact."""
+    validate_panel_demand_v1(panel)
+
+
+def panel_point_forecast_v1(frame: pd.DataFrame) -> PanelPointForecastV1:
+    """
+    Validate and construct a V1 panel point forecast artifact.
+
+    This is the canonical, explicit entrypoint for point forecast panels.
+    """
+    return PanelPointForecastV1.from_frame(frame)
+
+
+def panel_quantile_forecast_v1(frame: pd.DataFrame) -> PanelQuantileForecastV1:
+    """
+    Validate and construct a V1 panel quantile forecast artifact.
+
+    This is the canonical, explicit entrypoint for quantile forecast panels.
+    """
+    return PanelQuantileForecastV1.from_frame(frame)
+
+
+# Backwards-compatible aliases (keep these stable for downstream users).
+def panel_point_v1(frame: pd.DataFrame) -> PanelPointForecastV1:
+    """Alias for `panel_point_forecast_v1` (kept for backwards compatibility)."""
+    return panel_point_forecast_v1(frame)
+
+
+def panel_quantile_v1(frame: pd.DataFrame) -> PanelQuantileForecastV1:
+    """Alias for `panel_quantile_forecast_v1` (kept for backwards compatibility)."""
+    return panel_quantile_forecast_v1(frame)
+
+
+def cost_asymmetry_v1(frame: pd.DataFrame) -> CostAsymmetrySpecV1:
+    """Validate and construct a V1 cost-asymmetry specification artifact."""
+    return CostAsymmetrySpecV1.from_frame(frame)
+
+
+def panel_point_result_v1(frame: pd.DataFrame) -> PanelPointResultV1:
+    """Validate and construct a V1 panel point result artifact."""
+    return PanelPointResultV1.from_frame(frame)
+
+
+__all__ = [
+    "cost_asymmetry_v1",
+    "panel_demand_v1",
+    "panel_point_forecast_v1",
+    "panel_point_result_v1",
+    "panel_point_v1",
+    "panel_quantile_forecast_v1",
+    "panel_quantile_v1",
+]

eb_contracts/contracts/__init__.py

@@ -0,0 +1,9 @@
+"""
+Contract artifacts and internal contract helpers.
+
+This package contains versioned contract artifacts (e.g., demand panels, forecasts,
+results, readiness diagnostics) and internal utilities used by those artifacts.
+
+Do not treat this package as a stable public API surface. Prefer `eb_contracts.api`
+for user-facing entrypoints.
+"""

eb_contracts/contracts/_internal/__init__.py

@@ -0,0 +1,8 @@
+"""
+Internal helpers for contract artifacts.
+
+This package contains shared runtime, typing, and enforcement utilities used
+internally by contract artifacts.
+
+This is not a public API. Imports from this package may change without notice.
+"""

eb_contracts/contracts/_internal/runtime.py

@@ -0,0 +1,48 @@
+"""
+Runtime configuration for contract validation.
+
+This module provides a minimal runtime surface used by contract validators to
+determine validation behavior (e.g., strict, warn, off).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+import contextvars
+from dataclasses import dataclass
+from typing import Literal
+
+ValidationMode = Literal["strict", "warn", "off"]
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeConfig:
+    """Runtime configuration controlling validation behavior."""
+
+    validation: ValidationMode = "strict"
+
+
+_runtime_var: contextvars.ContextVar[RuntimeConfig | None] = contextvars.ContextVar(
+    "eb_contracts_runtime",
+    default=None,
+)
+
+
+def get_runtime() -> RuntimeConfig:
+    """Return the active runtime configuration."""
+    cfg = _runtime_var.get()
+    if cfg is None:
+        cfg = RuntimeConfig()
+        _runtime_var.set(cfg)
+    return cfg
+
+
+@contextmanager
+def set_validation_mode(mode: ValidationMode) -> Iterator[None]:
+    """Temporarily set validation behavior within a context."""
+    token = _runtime_var.set(RuntimeConfig(validation=mode))
+    try:
+        yield
+    finally:
+        _runtime_var.reset(token)

eb_contracts/contracts/_internal/typing.py

@@ -0,0 +1,37 @@
+"""
+Shared typing definitions for EB contracts.
+
+This module centralizes type aliases and lightweight protocol definitions
+used across contract artifacts, validators, and public entrypoints.
+
+It contains no runtime logic.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, TypeAlias
+
+import pandas as pd
+
+######################################
+# Core data structures
+######################################
+
+# Canonical DataFrame type used throughout contract artifacts.
+Frame: TypeAlias = pd.DataFrame
+
+
+######################################
+# Validation behavior
+######################################
+
+ValidationMode: TypeAlias = Literal["strict", "warn", "off"]
+
+
+######################################
+# Contract markers
+######################################
+
+# Marker alias for validated contract artifacts.
+# Contract classes typically expose a `.frame` attribute of type Frame.
+ContractArtifact: TypeAlias = object

eb_contracts/contracts/context/__init__.py

@@ -0,0 +1,14 @@
+"""
+Public context contract API.
+"""
+
+from __future__ import annotations
+
+######################################
+# Public API
+######################################
+from eb_contracts.contracts.context.v1.run_context import RunContextV1
+
+__all__ = [
+    "RunContextV1",
+]

eb_contracts/contracts/context/v1/__init__.py

@@ -0,0 +1,8 @@
+"""
+Context contract artifacts (version 1).
+
+This package contains version 1 context-related contract artifacts, including
+validated run-level metadata used for provenance and governance.
+
+Artifacts in this package are versioned and may evolve in future releases.
+"""

eb_contracts/contracts/context/v1/run_context.py

@@ -0,0 +1,202 @@
+"""
+Context contract models (V1).
+
+This module defines V1 context artifacts for attaching non-tabular metadata to
+forecasts, costs, and results.
+
+V1 includes:
+- RunContextV1: run-level metadata describing provenance and semantics
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import ClassVar, Final
+
+from eb_contracts.contracts._internal.runtime import get_runtime
+from eb_contracts.validation.errors import ContractViolation, ContractViolationError
+
+######################################
+# Contract artifacts
+######################################
+
+
+@dataclass(frozen=True, slots=True)
+class RunContextV1:
+    """Validated run-level context metadata."""
+
+    run_id: str
+    issued_at: datetime
+
+    model_id: str | None = None
+    dataset_id: str | None = None
+
+    horizon: int | None = None
+    interval_minutes: int | None = None
+    tz: str | None = None
+
+    tags: dict[str, str] | None = None
+
+    CONTRACT_NAME: ClassVar[Final[str]] = "RunContextV1"
+
+    @classmethod
+    def from_values(
+        cls,
+        *,
+        run_id: str,
+        issued_at: datetime,
+        model_id: str | None = None,
+        dataset_id: str | None = None,
+        horizon: int | None = None,
+        interval_minutes: int | None = None,
+        tz: str | None = None,
+        tags: dict[str, str] | None = None,
+    ) -> RunContextV1:
+        violations = validate_run_context_v1(
+            run_id=run_id,
+            issued_at=issued_at,
+            model_id=model_id,
+            dataset_id=dataset_id,
+            horizon=horizon,
+            interval_minutes=interval_minutes,
+            tz=tz,
+            tags=tags,
+        )
+        _raise_or_warn(cls.CONTRACT_NAME, violations)
+        return cls(
+            run_id=run_id,
+            issued_at=issued_at,
+            model_id=model_id,
+            dataset_id=dataset_id,
+            horizon=horizon,
+            interval_minutes=interval_minutes,
+            tz=tz,
+            tags=tags,
+        )
+
+
+######################################
+# Validators
+######################################
+
+
+def validate_run_context_v1(
+    *,
+    run_id: str,
+    issued_at: datetime,
+    model_id: str | None,
+    dataset_id: str | None,
+    horizon: int | None,
+    interval_minutes: int | None,
+    tz: str | None,
+    tags: dict[str, str] | None,
+) -> list[ContractViolation]:
+    """Validate values against the RunContextV1 contract."""
+    violations: list[ContractViolation] = []
+
+    if not run_id or not isinstance(run_id, str):
+        violations.append(
+            ContractViolation(
+                code="invalid_run_id",
+                message="run_id must be a non-empty string.",
+            )
+        )
+
+    if not isinstance(issued_at, datetime):
+        violations.append(
+            ContractViolation(
+                code="invalid_issued_at",
+                message="issued_at must be a datetime.",
+            )
+        )
+
+    if horizon is not None and horizon <= 0:
+        violations.append(
+            ContractViolation(
+                code="invalid_horizon",
+                message="horizon must be a positive integer when provided.",
+            )
+        )
+
+    if interval_minutes is not None and interval_minutes <= 0:
+        violations.append(
+            ContractViolation(
+                code="invalid_interval_minutes",
+                message="interval_minutes must be a positive integer when provided.",
+            )
+        )
+
+    if tags is not None:
+        if not isinstance(tags, dict):
+            violations.append(
+                ContractViolation(
+                    code="invalid_tags",
+                    message="tags must be a dict[str, str] when provided.",
+                )
+            )
+        else:
+            for k, v in tags.items():
+                if not isinstance(k, str) or not k:
+                    violations.append(
+                        ContractViolation(
+                            code="invalid_tag_key",
+                            message="All tag keys must be non-empty strings.",
+                        )
+                    )
+                    break
+                if not isinstance(v, str):
+                    violations.append(
+                        ContractViolation(
+                            code="invalid_tag_value",
+                            message="All tag values must be strings.",
+                        )
+                    )
+                    break
+
+    if model_id is not None and not isinstance(model_id, str):
+        violations.append(
+            ContractViolation(
+                code="invalid_model_id",
+                message="model_id must be a string when provided.",
+            )
+        )
+
+    if dataset_id is not None and not isinstance(dataset_id, str):
+        violations.append(
+            ContractViolation(
+                code="invalid_dataset_id",
+                message="dataset_id must be a string when provided.",
+            )
+        )
+
+    if tz is not None and (not isinstance(tz, str) or not tz):
+        violations.append(
+            ContractViolation(
+                code="invalid_tz",
+                message="tz must be a non-empty string when provided.",
+            )
+        )
+
+    return violations
+
+
+######################################
+# Internal helpers
+######################################
+
+
+def _raise_or_warn(contract: str, violations: list[ContractViolation]) -> None:
+    """Apply runtime validation behavior."""
+    if not violations:
+        return
+
+    mode = get_runtime().validation
+    if mode == "off":
+        return
+
+    if mode == "warn":
+        print(f"[eb-contracts] WARN: {contract}: " + "; ".join(v.message for v in violations))
+        return
+
+    raise ContractViolationError(contract=contract, violations=violations)

eb_contracts/contracts/costs/__init__.py

@@ -0,0 +1,14 @@
+"""
+Public cost contract API.
+"""
+
+from __future__ import annotations
+
+######################################
+# Public API
+######################################
+from eb_contracts.contracts.costs.v1.cost_asymmetry_spec import CostAsymmetrySpecV1
+
+__all__ = [
+    "CostAsymmetrySpecV1",
+]

eb_contracts/contracts/costs/v1/__init__.py

@@ -0,0 +1,8 @@
+"""
+Cost contract artifacts (version 1).
+
+This package contains version 1 cost-related contract artifacts, including
+validated cost-asymmetry specifications used for evaluation and optimization.
+
+Artifacts in this package are versioned and may evolve in future releases.
+"""