eb-contracts 0.2.0__tar.gz

eb_contracts-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+    # Only trigger if relevant files change
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'LICENSE'
+  workflow_dispatch: # Allows manual "Run workflow" trigger
+
+# Cancel previous runs if you push new code to the same PR
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci:
+    # Use 'permissions' to be explicit for the called workflow
+    permissions:
+      contents: read
+      packages: read
+    uses: Economistician/eb-integration/.github/workflows/pr-gate.yml@main
+    with:
+      os: '["ubuntu-latest", "windows-latest"]'
+      python_versions: '["3.11", "3.12", "3.13"]'
+      tooling_python_version: "3.13"
+      run_precommit: true
+      enable_typecheck: true
+      import_module: "eb_contracts"
+      extras: "all"

eb_contracts-0.2.0/.github/workflows/pypi-smoke.yml

@@ -0,0 +1,20 @@
+name: PyPI Smoke Test
+
+on:
+  schedule:
+    - cron: "0 0 * * 0"  # Weekly on Sundays
+  workflow_run:
+    workflows: ["PyPI Release"]
+    types:
+      - completed
+  workflow_dispatch:      # Allows you to click "Run workflow" in GitHub UI
+
+jobs:
+  smoke-test:
+    # Only run if the release was a success, OR if it's a scheduled/manual run
+    if: ${{ github.event.workflow_run.conclusion == 'success' || github.event_name != 'workflow_run' }}
+    uses: Economistician/eb-integration/.github/workflows/pypi-smoke.yml@main
+    with:
+      python-version: "3.12"
+      package: "eb-contracts"
+      import_module: "eb_contracts"

eb_contracts-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,18 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  release:
+    name: Call Centralized PyPI Release
+    permissions:
+      contents: read
+    uses: Economistician/eb-integration/.github/workflows/pypi-release.yml@main
+    with:
+      python-version: "3.12"
+      build-command: "python -m build --sdist --wheel"
+    secrets: inherit

eb_contracts-0.2.0/.gitignore

@@ -0,0 +1,288 @@
+###############################################################################
+# Byte-compiled / optimized / DLL files
+###############################################################################
+__pycache__/
+**/__pycache__/
+*.py[cod]
+*$py.class
+
+
+###############################################################################
+# C extensions
+###############################################################################
+*.so
+
+
+###############################################################################
+# Distribution / packaging
+###############################################################################
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+
+###############################################################################
+# PyInstaller
+###############################################################################
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.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/
+cover/
+
+
+###############################################################################
+# Translations
+###############################################################################
+*.mo
+*.pot
+
+
+###############################################################################
+# Django
+###############################################################################
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+
+###############################################################################
+# Flask
+###############################################################################
+instance/
+.webassets-cache
+
+
+###############################################################################
+# Scrapy
+###############################################################################
+.scrapy
+
+
+###############################################################################
+# Sphinx documentation
+###############################################################################
+docs/_build/
+
+
+###############################################################################
+# PyBuilder
+###############################################################################
+.pybuilder/
+target/
+
+
+###############################################################################
+# Jupyter Notebook
+###############################################################################
+.ipynb_checkpoints/
+
+
+###############################################################################
+# IPython
+###############################################################################
+profile_default/
+ipython_config.py
+
+
+###############################################################################
+# pyenv
+###############################################################################
+# .python-version
+
+
+###############################################################################
+# pipenv
+###############################################################################
+# Pipfile.lock
+
+
+###############################################################################
+# UV
+###############################################################################
+# uv.lock
+
+
+###############################################################################
+# poetry
+###############################################################################
+# poetry.lock
+# poetry.toml
+
+
+###############################################################################
+# pdm
+###############################################################################
+.pdm-python
+.pdm-build/
+# pdm.lock
+# pdm.toml
+
+
+###############################################################################
+# pixi
+###############################################################################
+.pixi
+# pixi.lock
+
+
+###############################################################################
+# PEP 582
+###############################################################################
+__pypackages__/
+
+
+###############################################################################
+# Celery
+###############################################################################
+celerybeat-schedule
+celerybeat.pid
+
+
+###############################################################################
+# SageMath
+###############################################################################
+*.sage.py
+
+
+###############################################################################
+# Environments
+###############################################################################
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+
+###############################################################################
+# Spyder
+###############################################################################
+.spyderproject
+.spyproject
+
+
+###############################################################################
+# Rope
+###############################################################################
+.ropeproject
+
+
+###############################################################################
+# mkdocs
+###############################################################################
+/site
+
+
+###############################################################################
+# mypy
+###############################################################################
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+
+###############################################################################
+# Pyre
+###############################################################################
+.pyre/
+
+
+###############################################################################
+# pytype
+###############################################################################
+.pytype/
+
+
+###############################################################################
+# Cython debug symbols
+###############################################################################
+cython_debug/
+
+
+###############################################################################
+# PyCharm
+###############################################################################
+# .idea/
+
+
+###############################################################################
+# Abstra
+###############################################################################
+.abstra/
+
+
+###############################################################################
+# Visual Studio Code
+###############################################################################
+# .vscode/
+
+
+###############################################################################
+# Ruff
+###############################################################################
+.ruff_cache/
+
+
+###############################################################################
+# PyPI configuration
+###############################################################################
+.pypirc
+
+
+###############################################################################
+# Cursor
+###############################################################################
+.cursorignore
+.cursorindexingignore
+
+
+###############################################################################
+# Marimo
+###############################################################################
+marimo/_static/
+marimo/_lsp/
+__marimo__/

eb_contracts-0.2.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Kyle Corrie
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

eb_contracts-0.2.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: eb-contracts
+Version: 0.2.0
+Summary: Electric Barometer data contracts and validation utilities.
+Project-URL: Homepage, https://github.com/Economistician/eb-contracts
+Project-URL: Repository, https://github.com/Economistician/eb-contracts
+Project-URL: Issues, https://github.com/Economistician/eb-contracts/issues
+Author: Electric Barometer
+License: BSD-3-Clause
+License-File: LICENSE
+Keywords: data-contracts,electric-barometer,forecasting,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: pandas>=2.0
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pyright>=1.1.380; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Electric Barometer · Contracts (`eb-contracts`)
+
+![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)
+
+Data contract and validation layer for the Electric Barometer ecosystem, defining canonical schemas, semantics, and enforcement for forecasts, costs, results, and run context.
+
+---
+
+## Overview
+
+This repository contains the data contract and validation layer of the Electric Barometer ecosystem. It defines the canonical schemas, semantics, and invariants that govern how forecasts, costs, results, and contextual metadata are represented, validated, and exchanged across systems.
+
+Rather than producing forecasts, computing metrics, or applying optimization logic, this repository focuses on structural correctness and shared meaning: how data artifacts are shaped, what guarantees they provide, and how violations are detected and handled. By formalizing these contracts as versioned, validated artifacts, eb-contracts ensures that all downstream components operate on consistent, explicit, and auditable data interfaces—reducing ambiguity, preventing silent errors, and enabling long-term evolution without breaking consumers.
+
+---
+
+## Role in the Electric Barometer Ecosystem
+
+`eb-contracts` defines the canonical data contracts and validation boundaries used throughout the Electric Barometer ecosystem. It is responsible for specifying how core data artifacts—such as forecasts, cost specifications, evaluation results, and run context—are structured, interpreted, and validated before they are consumed by downstream systems.
+
+This repository focuses exclusively on data shape, semantic consistency, and enforcement. It does not generate forecasts, compute metrics, select parameters, perform optimization, or orchestrate evaluation workflows. Those responsibilities are handled by adjacent layers in the ecosystem that produce predictions, compute metric values, calibrate parameters, or apply decision logic in operational settings.
+
+By separating data contracts and validation from computation and policy concerns, eb-contracts provides a stable, versioned interface layer that enables interoperability, reduces ambiguity, and ensures that all components of the Electric Barometer ecosystem operate on shared, explicit assumptions—supporting long-term evolution without breaking consumers.
+
+---
+
+## Installation
+
+`eb-optimization` is distributed as a standard Python package.
+
+```bash
+pip install eb-contracts
+```
+
+---
+
+## Core Concepts
+
+- **Canonical data contracts** — Core data artifacts (forecasts, cost specifications, results, and context) are represented using explicit, versioned schemas rather than implicit conventions or ad-hoc DataFrame shapes.
+
+- **Semantic consistency** — Column names, units, grain, and meaning are standardized and enforced so that downstream systems can rely on shared interpretation rather than contextual knowledge or undocumented assumptions.
+
+- **Validation as a boundary** — Contract validation establishes a clear boundary between “valid” and “invalid” data, preventing silent failures and making structural issues visible at ingestion time rather than during downstream computation.
+
+- **Versioned evolution** — Contracts are versioned to allow schemas and semantics to evolve over time without breaking existing consumers, enabling forward progress while preserving backward compatibility.
+
+- **Explicit migration** — Adaptation from external or legacy data formats into contract-compliant artifacts is performed through explicit migration utilities, avoiding implicit coercion or guesswork.
+
+- **Separation of structure from logic** — Data shape and meaning are defined independently of metric computation, optimization, or execution logic, ensuring that structural correctness is not entangled with algorithmic behavior.
+
+---
+
+## Minimal Example
+
+The example below illustrates a typical contract workflow using `eb-contracts`: adapting an external forecast frame into a canonical contract artifact and validating it at the system boundary.
+
+```python
+import pandas as pd
+
+from eb_contracts.migrate import (
+    PanelPointColumns,
+    to_panel_point_v1,
+)
+from eb_contracts.validate import panel_point_v1
+from eb_contracts._runtime import set_validation_mode
+
+# External (non-canonical) forecast data
+raw = pd.DataFrame(
+    {
+        "store": ["A", "A"],
+        "timestamp": [
+            pd.Timestamp("2025-01-01 00:00:00"),
+            pd.Timestamp("2025-01-01 00:30:00"),
+        ],
+        "actual": [10.0, 12.0],
+        "forecast": [11.0, 13.0],
+    }
+)
+
+# Explicitly map external columns to the EB contract
+columns = PanelPointColumns(
+    entity_id="store",
+    interval_start="timestamp",
+    y_true="actual",
+    y_pred="forecast",
+)
+
+# Enable strict validation at the contract boundary
+with set_validation_mode("strict"):
+    forecast = to_panel_point_v1(raw, columns=columns)
+
+# `forecast` is now a validated PanelPointForecastV1 artifact
+print(type(forecast))
+```
+
+---
+
+## License
+
+BSD 3-Clause License.
+© 2025 Kyle Corrie.

eb_contracts-0.2.0/README.md

@@ -0,0 +1,101 @@
+# Electric Barometer · Contracts (`eb-contracts`)
+
+![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)
+
+Data contract and validation layer for the Electric Barometer ecosystem, defining canonical schemas, semantics, and enforcement for forecasts, costs, results, and run context.
+
+---
+
+## Overview
+
+This repository contains the data contract and validation layer of the Electric Barometer ecosystem. It defines the canonical schemas, semantics, and invariants that govern how forecasts, costs, results, and contextual metadata are represented, validated, and exchanged across systems.
+
+Rather than producing forecasts, computing metrics, or applying optimization logic, this repository focuses on structural correctness and shared meaning: how data artifacts are shaped, what guarantees they provide, and how violations are detected and handled. By formalizing these contracts as versioned, validated artifacts, eb-contracts ensures that all downstream components operate on consistent, explicit, and auditable data interfaces—reducing ambiguity, preventing silent errors, and enabling long-term evolution without breaking consumers.
+
+---
+
+## Role in the Electric Barometer Ecosystem
+
+`eb-contracts` defines the canonical data contracts and validation boundaries used throughout the Electric Barometer ecosystem. It is responsible for specifying how core data artifacts—such as forecasts, cost specifications, evaluation results, and run context—are structured, interpreted, and validated before they are consumed by downstream systems.
+
+This repository focuses exclusively on data shape, semantic consistency, and enforcement. It does not generate forecasts, compute metrics, select parameters, perform optimization, or orchestrate evaluation workflows. Those responsibilities are handled by adjacent layers in the ecosystem that produce predictions, compute metric values, calibrate parameters, or apply decision logic in operational settings.
+
+By separating data contracts and validation from computation and policy concerns, eb-contracts provides a stable, versioned interface layer that enables interoperability, reduces ambiguity, and ensures that all components of the Electric Barometer ecosystem operate on shared, explicit assumptions—supporting long-term evolution without breaking consumers.
+
+---
+
+## Installation
+
+`eb-optimization` is distributed as a standard Python package.
+
+```bash
+pip install eb-contracts
+```
+
+---
+
+## Core Concepts
+
+- **Canonical data contracts** — Core data artifacts (forecasts, cost specifications, results, and context) are represented using explicit, versioned schemas rather than implicit conventions or ad-hoc DataFrame shapes.
+
+- **Semantic consistency** — Column names, units, grain, and meaning are standardized and enforced so that downstream systems can rely on shared interpretation rather than contextual knowledge or undocumented assumptions.
+
+- **Validation as a boundary** — Contract validation establishes a clear boundary between “valid” and “invalid” data, preventing silent failures and making structural issues visible at ingestion time rather than during downstream computation.
+
+- **Versioned evolution** — Contracts are versioned to allow schemas and semantics to evolve over time without breaking existing consumers, enabling forward progress while preserving backward compatibility.
+
+- **Explicit migration** — Adaptation from external or legacy data formats into contract-compliant artifacts is performed through explicit migration utilities, avoiding implicit coercion or guesswork.
+
+- **Separation of structure from logic** — Data shape and meaning are defined independently of metric computation, optimization, or execution logic, ensuring that structural correctness is not entangled with algorithmic behavior.
+
+---
+
+## Minimal Example
+
+The example below illustrates a typical contract workflow using `eb-contracts`: adapting an external forecast frame into a canonical contract artifact and validating it at the system boundary.
+
+```python
+import pandas as pd
+
+from eb_contracts.migrate import (
+    PanelPointColumns,
+    to_panel_point_v1,
+)
+from eb_contracts.validate import panel_point_v1
+from eb_contracts._runtime import set_validation_mode
+
+# External (non-canonical) forecast data
+raw = pd.DataFrame(
+    {
+        "store": ["A", "A"],
+        "timestamp": [
+            pd.Timestamp("2025-01-01 00:00:00"),
+            pd.Timestamp("2025-01-01 00:30:00"),
+        ],
+        "actual": [10.0, 12.0],
+        "forecast": [11.0, 13.0],
+    }
+)
+
+# Explicitly map external columns to the EB contract
+columns = PanelPointColumns(
+    entity_id="store",
+    interval_start="timestamp",
+    y_true="actual",
+    y_pred="forecast",
+)
+
+# Enable strict validation at the contract boundary
+with set_validation_mode("strict"):
+    forecast = to_panel_point_v1(raw, columns=columns)
+
+# `forecast` is now a validated PanelPointForecastV1 artifact
+print(type(forecast))
+```
+
+---
+
+## License
+
+BSD 3-Clause License.
+© 2025 Kyle Corrie.

eb_contracts-0.2.0/docs/api/definitions.md

@@ -0,0 +1,7 @@
+# Definitions
+
+This section documents shared definitions and semantic primitives exposed by `eb-contracts`.
+
+These definitions provide canonical constants, enums, and structural building blocks used across Electric Barometer contracts and APIs to ensure consistent interpretation of values and fields.
+
+::: eb_contracts.definitions

eb_contracts-0.2.0/docs/api/migrate_forecast.md

@@ -0,0 +1,7 @@
+# Forecast migration
+
+This section documents utilities for migrating forecast data between contract versions in `eb-contracts`.
+
+These helpers support forward-compatible evolution of forecast schemas by transforming historical or legacy forecast structures into their current canonical representations.
+
+::: eb_contracts.api.migrate_forecast

eb_contracts-0.2.0/docs/api/validate.md

@@ -0,0 +1,7 @@
+# Forecast migration
+
+This section documents utilities for migrating forecast data between contract versions in `eb-contracts`.
+
+These helpers support forward-compatible evolution of forecast schemas by transforming historical or legacy forecast structures into their current canonical representations.
+
+::: eb_contracts.api.migrate_forecast

eb_contracts-0.2.0/docs/index.md

@@ -0,0 +1,31 @@
+# eb-contracts
+
+`eb-contracts` defines the canonical data contracts, schemas, and structural interfaces used across the Electric Barometer ecosystem.
+
+This package establishes **shared meaning and shape**, ensuring that forecasts, evaluations, optimization outputs, and downstream systems interoperate consistently.
+
+## Scope
+
+This package is responsible for:
+
+- Defining canonical data structures and schemas
+- Formalizing inputs and outputs exchanged between EB components
+- Encoding shared assumptions about forecast results, costs, and runtime context
+- Providing validation and migration utilities for contract evolution
+
+It intentionally avoids implementing metrics, models, optimization logic, or workflows.
+
+## Contents
+
+- **Core contracts**
+  Canonical representations for forecasts, results, costs, and runtime context
+
+- **Validation utilities**
+  Tools for checking contract conformance and structural integrity
+
+- **Migration support**
+  Helpers for evolving contracts across versions
+
+## API reference
+
+- [Contract definitions](api/index.md)