energychain 0.1.0__tar.gz

energychain-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EnergyChain Contributors
+
+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.

energychain-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include scripts *.py
+recursive-include tests *.py
+prune .github

energychain-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: energychain
+Version: 0.1.0
+Summary: Composable, safety-first Python framework for AI-native energy applications
+Author: EnergyChain Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Atanseiye/energychain
+Project-URL: Repository, https://github.com/Atanseiye/energychain
+Project-URL: Issues, https://github.com/Atanseiye/energychain/issues
+Keywords: energy,solar,battery,AI,agents,energychain,SDK
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# EnergyChain
+
+**EnergyChain is the developer infrastructure through which AI applications can understand, interact with, and safely optimize energy systems—from solar installations and batteries to mini-grids, utilities, and electricity networks.**
+
+> Status: **v0.1.0 alpha**. Offline-first, Python-first, and read-only by default. Simulated energy data are **not live device measurements**.
+
+EnergyChain brings composable, vendor-neutral energy data types, connectors, safe callable tools, storage, deterministic energy calculations, a pluggable agent interface, and in-process workflows to Python developers. EnergyChain is a **separate project** from Energy Data Network (EDN).
+
+## Installation
+
+```bash
+python -m pip install energychain
+```
+
+To pin this release:
+
+```bash
+python -m pip install energychain==0.1.0
+```
+
+Requires Python 3.10 or newer. The core package uses **only Python standard-library runtime dependencies**.
+
+## Quickstart
+
+```python
+from energychain import EnergyChain
+
+chain = EnergyChain.demo()
+user = chain.principal("developer", allowed_sites={"demo-site"})
+
+assets = chain.tools.invoke("discover_assets", user, "demo-site")
+print([a.name for a in assets])
+
+result = chain.tools.invoke(
+    "estimate_battery_runtime", user, "demo-site",
+    arguments={"battery_id": "demo-battery", "load_w": 900, "reserve_pct": 20},
+)
+print(result)
+```
+
+**Security:** `principal()` is a **local-demo convenience**, not a production authentication mechanism. Production applications must authenticate principals, assign site-level permissions from a trusted service, and enforce authorization at API boundaries. The included connector simulator never sends live control commands.
+
+## Components available in 0.1
+
+| Component | Implementation |
+|---|---|
+| Energy models | Site, asset, metric, reading, event, tariff, energy plan |
+| Connectors | Abstract connector, registry, deterministic hybrid site simulator, CSV import |
+| Memory | In-process bounded memory, SQLite durable persistence |
+| Energy tools | Asset discovery, state, history, battery state, runtime and cost estimates, preferences |
+| Safety | Permission scope, site boundaries and optional action-specific execution approval |
+| Intelligence | Battery-runtime estimate, tariff cost, baseline mean forecast, outlier baseline |
+| Agent | Explicit tool selection plus optional injected text-model callback |
+| Workflow | In-process fail-closed sequential tool execution |
+| Observability | In-memory bounded trace events |
+| Developer experience | PyPI-ready packaging, examples, tests, CI and trusted-publisher release workflow |
+
+## Intentionally not included in 0.1
+
+- Authenticated integrations with third-party solar/battery vendors (no verified API credentials or access yet)
+- A production-ready control or dispatch runtime, remote device command implementation, or energy safety certification
+- Autonomous LLM tool selection, multi-agent coordination, event subscriptions, distributed scheduling or durable workflow retries
+- Production-grade multi-tenant identity, authorization server, encryption/key management, or high-volume telemetry infrastructure
+- Trained forecasting models, validated anomaly detection accuracy, hardware testing or independently measured energy savings
+- Managed EnergyChain Cloud, hosted APIs, TypeScript SDK, vector-search services or MCP adapter
+
+These are subsequent product-development efforts, not features to advertise as shipped.
+
+## Connect existing CSV exports
+
+Provide `asset_id,metric,value,timestamp,source` columns and register an explicit `EnergySite` and its `EnergyAsset` definitions. See `CSVConnector.from_csv(path, site=..., assets=...)`. The latest row is treated as the last *recorded* value (not necessarily live); caller must check freshness before operational decisions.
+
+## Design principles
+
+1. **Developer-first:** EnergyChain is software infrastructure for developers, not a national-grid control product.
+2. **Standard energy semantics:** W, Wh, %, UTC-offset-aware timestamps, data-source and quality fields.
+3. **Composable:** Connectors, tools, memory and language models can be independently replaced.
+4. **Data is not authority:** An LLM response cannot issue a physical command. Tools always check policies.
+5. **Provenance matters:** Simulated, estimated and measured values are explicitly labelled.
+6. **Tests and evidence:** Do not confuse synthetic demonstrations with field validation.
+
+## Local development
+
+```bash
+python -m pip install -e '.[dev]'
+python -m pytest -q
+python -m build
+python -m twine check dist/*
+python examples/quickstart.py
+```
+
+See [architecture](docs/architecture.md) for contract boundaries and limitations and [release guide](docs/releasing.md) for verified distribution steps.
+
+## Licensing and safety
+
+EnergyChain is distributed under the [MIT License](LICENSE). Published wheels and source archives are publicly downloadable even though the development repository is private. Alpha-quality software: not warranted for physically controlling energy equipment.

energychain-0.1.0/README.md

@@ -0,0 +1,96 @@
+# EnergyChain
+
+**EnergyChain is the developer infrastructure through which AI applications can understand, interact with, and safely optimize energy systems—from solar installations and batteries to mini-grids, utilities, and electricity networks.**
+
+> Status: **v0.1.0 alpha**. Offline-first, Python-first, and read-only by default. Simulated energy data are **not live device measurements**.
+
+EnergyChain brings composable, vendor-neutral energy data types, connectors, safe callable tools, storage, deterministic energy calculations, a pluggable agent interface, and in-process workflows to Python developers. EnergyChain is a **separate project** from Energy Data Network (EDN).
+
+## Installation
+
+```bash
+python -m pip install energychain
+```
+
+To pin this release:
+
+```bash
+python -m pip install energychain==0.1.0
+```
+
+Requires Python 3.10 or newer. The core package uses **only Python standard-library runtime dependencies**.
+
+## Quickstart
+
+```python
+from energychain import EnergyChain
+
+chain = EnergyChain.demo()
+user = chain.principal("developer", allowed_sites={"demo-site"})
+
+assets = chain.tools.invoke("discover_assets", user, "demo-site")
+print([a.name for a in assets])
+
+result = chain.tools.invoke(
+    "estimate_battery_runtime", user, "demo-site",
+    arguments={"battery_id": "demo-battery", "load_w": 900, "reserve_pct": 20},
+)
+print(result)
+```
+
+**Security:** `principal()` is a **local-demo convenience**, not a production authentication mechanism. Production applications must authenticate principals, assign site-level permissions from a trusted service, and enforce authorization at API boundaries. The included connector simulator never sends live control commands.
+
+## Components available in 0.1
+
+| Component | Implementation |
+|---|---|
+| Energy models | Site, asset, metric, reading, event, tariff, energy plan |
+| Connectors | Abstract connector, registry, deterministic hybrid site simulator, CSV import |
+| Memory | In-process bounded memory, SQLite durable persistence |
+| Energy tools | Asset discovery, state, history, battery state, runtime and cost estimates, preferences |
+| Safety | Permission scope, site boundaries and optional action-specific execution approval |
+| Intelligence | Battery-runtime estimate, tariff cost, baseline mean forecast, outlier baseline |
+| Agent | Explicit tool selection plus optional injected text-model callback |
+| Workflow | In-process fail-closed sequential tool execution |
+| Observability | In-memory bounded trace events |
+| Developer experience | PyPI-ready packaging, examples, tests, CI and trusted-publisher release workflow |
+
+## Intentionally not included in 0.1
+
+- Authenticated integrations with third-party solar/battery vendors (no verified API credentials or access yet)
+- A production-ready control or dispatch runtime, remote device command implementation, or energy safety certification
+- Autonomous LLM tool selection, multi-agent coordination, event subscriptions, distributed scheduling or durable workflow retries
+- Production-grade multi-tenant identity, authorization server, encryption/key management, or high-volume telemetry infrastructure
+- Trained forecasting models, validated anomaly detection accuracy, hardware testing or independently measured energy savings
+- Managed EnergyChain Cloud, hosted APIs, TypeScript SDK, vector-search services or MCP adapter
+
+These are subsequent product-development efforts, not features to advertise as shipped.
+
+## Connect existing CSV exports
+
+Provide `asset_id,metric,value,timestamp,source` columns and register an explicit `EnergySite` and its `EnergyAsset` definitions. See `CSVConnector.from_csv(path, site=..., assets=...)`. The latest row is treated as the last *recorded* value (not necessarily live); caller must check freshness before operational decisions.
+
+## Design principles
+
+1. **Developer-first:** EnergyChain is software infrastructure for developers, not a national-grid control product.
+2. **Standard energy semantics:** W, Wh, %, UTC-offset-aware timestamps, data-source and quality fields.
+3. **Composable:** Connectors, tools, memory and language models can be independently replaced.
+4. **Data is not authority:** An LLM response cannot issue a physical command. Tools always check policies.
+5. **Provenance matters:** Simulated, estimated and measured values are explicitly labelled.
+6. **Tests and evidence:** Do not confuse synthetic demonstrations with field validation.
+
+## Local development
+
+```bash
+python -m pip install -e '.[dev]'
+python -m pytest -q
+python -m build
+python -m twine check dist/*
+python examples/quickstart.py
+```
+
+See [architecture](docs/architecture.md) for contract boundaries and limitations and [release guide](docs/releasing.md) for verified distribution steps.
+
+## Licensing and safety
+
+EnergyChain is distributed under the [MIT License](LICENSE). Published wheels and source archives are publicly downloadable even though the development repository is private. Alpha-quality software: not warranted for physically controlling energy equipment.

energychain-0.1.0/docs/architecture.md

@@ -0,0 +1,33 @@
+# EnergyChain v0.1 architecture contract
+
+## Scope
+Python framework for reading, normalizing, remembering, analyzing and explaining basic energy observations. Included connectors are a synthetic hybrid site simulator and a read-only CSV telemetry-import adapter; no branded live vendor API is claimed. No first-party hosted services or direct control integration is included.
+
+## Component dependency direction
+`EnergyChain` assembles `ConnectorRegistry`, `EnergyMemory`, `ToolRegistry`, and `EnergyAgent`; workflow is an independent consumer of the tool registry. Energy adapters implement `EnergyConnector`. Authorized actions are checked at `ToolRegistry.invoke`. All default tool handlers are read/analysis only.
+
+## Domain conventions
+- Power (instantaneous) = W; energy (integrated) = Wh. Do not interchange.
+- Battery charge is percentage [0,100]; capacity is Wh.
+- Datetime objects must contain timezone information.
+- Source and data quality (measured, estimated, simulated) are mandatory for readings.
+- Assets and sites use stable, provider-independent identifiers; registry disallows duplicate IDs across connectors.
+
+## Trust boundaries
+- A caller constructs authenticated `Principal` from external authorization; `EnergyChain.principal()` is for demos only.
+- Every tool invocation is site-scoped, and handlers validate an asset's registered site against that scope.
+- A tool's permission level is not derived from LLM output.
+- The model cannot dynamically invoke tools via `EnergyAgent` v0.1.
+- Standard connector `execute` fails with `UnsupportedCapability` unless consciously implemented by a third-party adapter.
+- Future physical execution must enforce equipment constraints, device authorization, human approval, auditable logs and post-action verification.
+- Local SQLite and in-memory stores are not substitutes for production tenant isolation or infrastructure security.
+- Tool return data must be treated as untrusted, and the runtime is not a prompt-injection defense for arbitrary LLM implementations.
+
+## Memory semantics
+In-memory records are bounded per site; SQLite stores readings, events, notes and JSON-encoded preferences. The caller must ensure every recording matches the actual site identity. A dedicated production memory backend should enforce ownership at the storage layer and add retention/deletion policies.
+
+## Calculations
+Battery runtime computes `capacity_wh * max(soc - reserve,0)/100 * efficiency / load_w`. A zero load returns `None` (unbounded in this idealized equation, not infinite guaranteed device runtime). Mean forecast and z-score anomaly detection are transparent baselines, not validated ML predictors. Financial calculation multiplies energy (Wh)/1000 by tariff currency per kWh.
+
+## Next compatibility points
+Connectors: authenticated public vendor APIs; memory: production time-series store; models: external LLM APIs; workflows: checkpoints and idempotency; adapters: MCP/other agent runtimes; future optional hosted offering.

energychain-0.1.0/docs/releasing.md

@@ -0,0 +1,88 @@
+# Publishing the `energychain` distribution
+
+**Do not claim `pip install energychain` works until the release exists on https://pypi.org/project/energychain/** and the installed package has been smoke-tested using a clean environment.
+
+## Owner decisions before the first public release
+
+The repository is the existing **private** https://github.com/Atanseiye/energychain.
+Continue its history; do not recreate it or change its visibility.
+
+The owner selected the **MIT License** and approved public SDK distribution on
+26 October 2026. `LICENSE` contains the terms; `[project]` declares `license = "MIT"`
+and `license-files = ["LICENSE"]`. The build requires `setuptools>=77` for PEP 639
+license metadata. Keep the license in both wheels and source archives.
+
+Public distribution includes the wheel **and source archive**. The publishing
+workflow fails before upload if the built artifacts lack license metadata/files.
+This is an artifact check, not proof of copyright ownership or legal clearance.
+
+## Account setup
+
+1. Check `https://pypi.org/pypi/energychain/json` immediately before publishing.
+   A 404 means no published project is visible; it does not guarantee the name is
+   reservable. If another party owns it, stop rather than uploading a substitute.
+2. Sign in at https://pypi.org/manage/account/publishing/ and add a pending GitHub
+   Trusted Publisher with these exact values:
+
+   | Field | Value |
+   | --- | --- |
+   | PyPI project | `energychain` |
+   | GitHub owner | `Atanseiye` |
+   | Repository | `energychain` |
+   | Workflow filename | `publish.yml` |
+   | Environment | `pypi` |
+
+   A pending publisher does not reserve the name. For an existing project owned by
+   this account, configure the publisher in that project's Publishing settings.
+3. In repository **Settings → Environments**, create `pypi`. Keep the repository
+   private. Set deployment rules/reviewers supported by the account as appropriate.
+   The workflow grants `id-token: write` only to the isolated publishing job;
+   no PyPI password or long-lived token belongs in the repository or its secrets.
+
+These account steps require authenticated owner access. A committed workflow does
+not configure the pending publisher in PyPI or verify the environment's settings.
+
+## Validate the release commit
+
+```bash
+python -m pip install -e '.[dev]'
+python -m ruff check --isolated --select E4,E7,E9,F src tests scripts examples
+python -m pytest -q
+python -m build
+python -m twine check --strict dist/*
+python scripts/check_dist.py --tag v0.1.0 --require-license
+```
+
+Start with an empty `dist/` directory. `python -m build` builds the wheel from the
+source archive, and `check_dist.py` checks that both contain the same SDK and
+matching name/version metadata. The license check is mandatory for publishing.
+Omit only `--require-license` when checking technical readiness before the owner
+has selected terms; that does not authorize a public release.
+
+Install the built wheel into a new virtualenv with `--no-index --no-deps`, then run
+`python -I scripts/smoke_test.py` using that environment's Python. `-I` prevents the
+checkout or `PYTHONPATH` from masking an incomplete wheel. CI does this on Python
+3.10–3.13 on Linux and Python 3.12 on Windows.
+
+## Publish and prove installation
+
+1. Ensure the exact release commit is on `main`, its CI is green, licensing is
+   settled and PyPI/account setup is complete.
+2. Create and publish a non-prerelease GitHub Release tagged `v0.1.0` at that commit.
+   `.github/workflows/publish.yml` repeats CI, verifies main ancestry and tag/version
+   agreement, validates licensing and tests the exact wheel before uploading.
+3. The separate `publish` job obtains short-lived PyPI credentials through GitHub
+   OIDC and publishes the previously tested artifacts. Actions are pinned to full
+   commit hashes. No code build or checkout runs in the OIDC-enabled job.
+4. The `verify` job runs `python scripts/verify_pypi.py`. It checks official PyPI
+   metadata and SHA256 hashes against the tested artifacts, creates a new Python
+   environment, and performs an **unpinned** install of `energychain` using only
+   `https://pypi.org/simple/`, without cache, local wheels or extra indexes. It checks
+   the installed version, official download URL, wheel hash, imports and SDK smoke
+   behavior. Success is reported only after that check passes.
+
+If upload succeeds but verification fails, inspect the verification error before
+retrying. PyPI release filenames cannot be overwritten. After a successful upload,
+rerun only the failed verification job rather than uploading the same files again.
+
+A **private GitHub repository does not make a PyPI distribution private**. Published wheels/sdists and their source can generally be downloaded by anyone. Decide whether the package source is suitable for public distribution before publishing.

energychain-0.1.0/examples/custom_model.py

@@ -0,0 +1,13 @@
+"""How to plug any proprietary or local LLM into EnergyChain."""
+from energychain import CallableTextModel, EnergyChain
+
+
+def my_llm(system: str, user: str, context: str) -> str:
+    # Replace with a provider SDK or local LLM call; a genuine LLM is not bundled.
+    return f"Prompt: {user}; available data: {context}"
+
+chain = EnergyChain.demo()
+p = chain.principal("developer", allowed_sites={"demo-site"})
+agent = chain.agent(CallableTextModel(my_llm))
+print(agent.run("What is my charge?", principal=p, site_id="demo-site",
+                tool_name="get_battery_state", tool_arguments={"asset_id": "demo-battery"}).answer)

energychain-0.1.0/examples/quickstart.py

@@ -0,0 +1,16 @@
+"""Run with: python examples/quickstart.py after pip install energychain"""
+from energychain import EnergyChain
+
+chain = EnergyChain.demo()
+user = chain.principal("example-user", allowed_sites={"demo-site"})
+print("Assets:", [asset.name for asset in chain.tools.invoke("discover_assets", user, "demo-site")])
+state = chain.tools.invoke("get_battery_state", user, "demo-site",
+                           arguments={"asset_id": "demo-battery"})
+print("Battery charge:", state["state_of_charge"].value, "% (SIMULATED)")
+estimate = chain.tools.invoke("estimate_battery_runtime", user, "demo-site",
+                              arguments={"battery_id": "demo-battery", "load_w": 900})
+print("Estimated backup hours:", round(estimate["hours"], 2))
+response = chain.agent().run("Can the site supply backup power?", principal=user,
+                             site_id="demo-site", tool_name="estimate_battery_runtime",
+                             tool_arguments={"battery_id": "demo-battery", "load_w": 900})
+print(response.answer)

energychain-0.1.0/examples/solar_insights.py

@@ -0,0 +1,13 @@
+"""Synthetic 24-hour solar generation insights without a model or vendor credential."""
+from datetime import datetime, timedelta, timezone
+from energychain import EnergyChain, simple_average_forecast
+
+chain = EnergyChain.demo()
+principal = chain.principal("demo", allowed_sites={"demo-site"})
+end = datetime.now(timezone.utc)
+readings = chain.tools.invoke("get_energy_history", principal, "demo-site", arguments={
+    "asset_id": "demo-solar", "metric": "power_w", "start": end-timedelta(hours=23), "end": end})
+forecast = simple_average_forecast(readings, horizon_hours=4)
+print("Synthetic hourly readings:", len(readings))
+print("Baseline forecast W:", forecast)
+print("Warning: simulation and simple mean baseline, not a trained forecast or validated estimate.")

energychain-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "energychain"
+version = "0.1.0"
+license = "MIT"
+license-files = ["LICENSE"]
+description = "Composable, safety-first Python framework for AI-native energy applications"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{name = "EnergyChain Contributors"}]
+keywords = ["energy", "solar", "battery", "AI", "agents", "energychain", "SDK"]
+classifiers = ["Development Status :: 3 - Alpha", "Intended Audience :: Developers", "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 :: Scientific/Engineering", "Topic :: Software Development :: Libraries :: Python Modules"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "build>=1", "twine>=5", "ruff>=0.6"]
+
+[project.urls]
+Homepage = "https://github.com/Atanseiye/energychain"
+Repository = "https://github.com/Atanseiye/energychain"
+Issues = "https://github.com/Atanseiye/energychain/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F"]

energychain-0.1.0/scripts/check_dist.py

@@ -0,0 +1,87 @@
+"""Check release artifacts without importing the working tree or contacting an index."""
+from __future__ import annotations
+
+import argparse
+import ast
+from email.parser import BytesParser
+import hashlib
+import json
+from pathlib import Path
+import tarfile
+import zipfile
+
+
+def check_distributions(dist: Path, *, tag: str | None = None,
+                        require_license: bool = False) -> dict:
+    wheels = list(dist.glob("*.whl"))
+    sdists = list(dist.glob("*.tar.gz"))
+    if len(wheels) != 1 or len(sdists) != 1 or len(list(dist.iterdir())) != 2:
+        raise ValueError("dist must contain exactly one wheel and one source distribution")
+    with zipfile.ZipFile(wheels[0]) as wheel:
+        names = wheel.namelist()
+        metadata_name = next(n for n in names if n.endswith(".dist-info/METADATA"))
+        metadata = BytesParser().parsebytes(wheel.read(metadata_name))
+        init = ast.parse(wheel.read("energychain/__init__.py"))
+        source_version = next(
+            ast.literal_eval(n.value) for n in init.body if isinstance(n, ast.Assign)
+            and any(isinstance(t, ast.Name) and t.id == "__version__" for t in n.targets))
+        version = metadata["Version"]
+        if metadata["Name"] != "energychain" or version != source_version:
+            raise ValueError("distribution name/version does not match the SDK")
+        if wheels[0].name != f"energychain-{version}-py3-none-any.whl":
+            raise ValueError("unexpected wheel name or compatibility tag")
+        if metadata["Requires-Python"] != ">=3.10":
+            raise ValueError("unexpected Python compatibility metadata")
+        if tag is not None and tag != f"v{version}":
+            raise ValueError(f"release tag must be v{version}; received {tag!r}")
+        if any("extra ==" not in r for r in metadata.get_all("Requires-Dist", [])):
+            raise ValueError("core package must remain free of runtime dependencies")
+        license_terms = metadata["License-Expression"] or metadata["License"]
+        license_names = metadata.get_all("License-File", [])
+        if require_license:
+            if not license_terms or not license_names:
+                raise ValueError("owner-approved license metadata and LICENSE file are required")
+            license_payloads = [
+                wheel.read(n) for n in names
+                if any(n.endswith("/" + f) for f in license_names)]
+            if not license_payloads or not all(p.strip() for p in license_payloads):
+                raise ValueError("wheel is missing the selected licensing terms")
+        sdk_files = {n: wheel.read(n) for n in names if n.startswith("energychain/")}
+    with tarfile.open(sdists[0], "r:gz") as sdist:
+        prefix = f"energychain-{version}/"
+        pkg_info = sdist.extractfile(prefix + "PKG-INFO")
+        if pkg_info is None:
+            raise ValueError("source distribution has no PKG-INFO")
+        source_metadata = BytesParser().parsebytes(pkg_info.read())
+        if any(source_metadata[key] != metadata[key] for key in (
+                "Name", "Version", "Requires-Python", "License-Expression", "License")):
+            raise ValueError("wheel and source metadata differ")
+        source_names = {n.name for n in sdist.getmembers()}
+        if sdists[0].name != f"energychain-{version}.tar.gz":
+            raise ValueError("unexpected source distribution name")
+        for name, contents in sdk_files.items():
+            member = sdist.extractfile(prefix + "src/" + name)
+            if member is None or member.read() != contents:
+                raise ValueError(f"wheel/source SDK content differs: {name}")
+        if require_license and any(prefix + f not in source_names for f in license_names):
+            raise ValueError("source distribution is missing licensing terms")
+    return {
+        "name": "energychain", "version": version,
+        "license_selected": bool(license_terms and license_names),
+        "sha256": {p.name: hashlib.sha256(p.read_bytes()).hexdigest()
+                   for p in sorted(wheels + sdists)},
+    }
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--dist", type=Path, default=Path("dist"))
+    parser.add_argument("--tag")
+    parser.add_argument("--require-license", action="store_true")
+    args = parser.parse_args()
+    try:
+        result = check_distributions(
+            args.dist, tag=args.tag, require_license=args.require_license)
+    except (ValueError, KeyError, StopIteration) as exc:
+        parser.exit(1, f"Release blocked: {exc}\n")
+    print(json.dumps(result, indent=2))

energychain-0.1.0/scripts/smoke_test.py

@@ -0,0 +1,74 @@
+"""Exercise an installed distribution. Run with python -I in a clean virtualenv."""
+from datetime import datetime, timezone
+from importlib.metadata import distribution
+import json
+from pathlib import Path
+import tempfile
+
+import energychain
+from energychain import (
+    Approval, AssetKind, CSVConnector, EnergyAsset, EnergyChain, EnergySite,
+    Permission, Principal, SQLiteEnergyMemory, ToolRegistry, ToolSpec,
+)
+from energychain.exceptions import ApprovalRequired, PermissionDenied
+
+
+def smoke_test():
+    installed = distribution("energychain")
+    assert installed.metadata["Name"] == "energychain"
+    assert installed.version == energychain.__version__
+    assert Path(energychain.__file__).resolve().is_relative_to(
+        Path(installed.locate_file("")).resolve()), "import resolved outside installed distribution"
+    assert not any("extra ==" not in r for r in (installed.requires or []))
+    for name in energychain.__all__:
+        assert hasattr(energychain, name), name
+    chain = EnergyChain.demo()
+    user = chain.principal("smoke", allowed_sites={"demo-site"})
+    assert len(chain.tools.invoke("discover_assets", user, "demo-site")) == 4
+    state = chain.tools.invoke("get_battery_state", user, "demo-site",
+                               arguments={"asset_id": "demo-battery"})
+    assert state["state_of_charge"].quality == "simulated"
+    assert chain.tools.invoke("estimate_energy_cost", user, "demo-site",
+                              arguments={"energy_wh": 2000, "price_per_kwh": 100})["cost"] == 200
+    try:
+        chain.tools.invoke("discover_assets", user, "other-site")
+    except PermissionDenied:
+        pass
+    else:
+        raise AssertionError("cross-site access was allowed")
+    tools = ToolRegistry()
+    tools.register(ToolSpec("act", "test-only command", Permission.EXECUTE,
+                            lambda *, site_id: site_id))
+    operator = Principal("operator", frozenset({"site"}), frozenset({Permission.EXECUTE}))
+    try:
+        tools.invoke("act", operator, "site")
+    except ApprovalRequired:
+        pass
+    else:
+        raise AssertionError("execution did not require approval")
+    assert tools.invoke("act", operator, "site",
+                        approval=Approval("operator", "site", "act", True)) == "site"
+    with tempfile.TemporaryDirectory() as directory:
+        csv = Path(directory) / "readings.csv"
+        csv.write_text("asset_id,metric,value,timestamp,source\n"
+                       "load,power_w,100,2026-10-25T10:00:00Z,export\n", encoding="utf-8")
+        connector = CSVConnector.from_csv(
+            csv, site=EnergySite("site", "Site"),
+            assets=[EnergyAsset("load", "site", "Load", AssetKind.LOAD)])
+        reading = connector.read("load", "power_w")
+        assert reading.value == 100
+        database = Path(directory) / "readings.db"
+        with SQLiteEnergyMemory(database) as memory:
+            memory.add_reading("site", reading)
+            memory.set_preference("site", "reserve_pct", 20)
+        with SQLiteEnergyMemory(database) as memory:
+            assert memory.preferences("site") == {"reserve_pct": 20}
+            assert memory.history("site", "load", "power_w",
+                                  datetime(2026, 10, 25, tzinfo=timezone.utc),
+                                  datetime(2026, 10, 26, tzinfo=timezone.utc)) == [reading]
+    print(json.dumps({"name": installed.metadata["Name"], "version": installed.version,
+                      "import_path": energychain.__file__, "smoke_test": "passed"}, indent=2))
+
+
+if __name__ == "__main__":
+    smoke_test()