synergyplus 0.2.0__py3-none-any.whl

synergyplus/__init__.py

@@ -0,0 +1,19 @@
+"""SynergyPlus Python SDK (CONTRACT §3).
+
+    from synergyplus import SynergyClient, ArtifactRef
+
+    sp = SynergyClient("http://localhost:8090", token="synergy-dev-key")
+    sim = sp.submit_simulation(
+        engine_version="24.1.0",
+        model=ArtifactRef("s3://models/sample/baseline.idf"),
+        weather=ArtifactRef("s3://weather/sample/chicago.epw"),
+    )
+    sp.wait(sim["id"])
+    print(sp.get_results(sim["id"]))
+"""
+
+from .client import SynergyClient
+from .models import ArtifactRef, Variant, sha256_file
+
+__all__ = ["SynergyClient", "ArtifactRef", "Variant", "sha256_file"]
+__version__ = "0.2.0"

synergyplus/client.py

@@ -0,0 +1,179 @@
+"""HTTP client for the SynergyPlus apiserver (CONTRACT §3).
+
+    from synergyplus import SynergyClient, ArtifactRef
+
+    sp = SynergyClient("http://localhost:8090", token="synergy-dev-key")
+    sim = sp.submit_simulation(
+        engine_version="24.1.0",
+        model=ArtifactRef("s3://models/sample/baseline.idf"),
+        weather=ArtifactRef("s3://weather/sample/chicago.epw"),
+    )
+    sp.wait(sim["id"])
+    print(sp.get_results(sim["id"]))
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Optional, Sequence, Union
+from urllib.parse import urlparse
+
+import requests
+
+from .models import ArtifactRef, Variant, as_ref, sha256_file
+
+_TERMINAL = {"succeeded", "failed"}
+
+
+class SynergyClient:
+    def __init__(self, base_url: str, token: Optional[str] = None, timeout: float = 30.0):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = requests.Session()
+        if token:
+            self._session.headers["Authorization"] = f"Bearer {token}"
+
+    # -- health ----------------------------------------------------------------
+
+    def healthz(self) -> bool:
+        resp = self._session.get(f"{self.base_url}/healthz", timeout=self.timeout)
+        return resp.ok
+
+    # -- simulations -----------------------------------------------------------
+
+    def submit_simulation(
+        self,
+        *,
+        engine_version: str,
+        model: Union[str, ArtifactRef],
+        weather: Union[str, ArtifactRef],
+        priority: Optional[int] = None,
+        extraction_spec: Optional[dict] = None,
+    ) -> dict:
+        """POST /v1/simulations → ``{id, state}`` (CONTRACT §3)."""
+        body: dict = {
+            "engineVersion": engine_version,
+            "model": as_ref(model),
+            "weather": as_ref(weather),
+        }
+        if priority is not None:
+            body["priority"] = priority
+        if extraction_spec is not None:
+            body["extractionSpec"] = extraction_spec
+
+        resp = self._session.post(
+            f"{self.base_url}/v1/simulations", json=body, timeout=self.timeout
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def get_simulation(self, sim_id: str) -> dict:
+        """GET /v1/simulations/{id} → ``{id, state, verdict?, result?}``."""
+        resp = self._session.get(
+            f"{self.base_url}/v1/simulations/{sim_id}", timeout=self.timeout
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def get_results(self, sim_id: str) -> dict:
+        """GET /v1/results/{simId} → ``{verdict, metrics, artifactUri}``."""
+        resp = self._session.get(
+            f"{self.base_url}/v1/results/{sim_id}", timeout=self.timeout
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def wait(self, sim_id: str, *, poll: float = 2.0, deadline: Optional[float] = None) -> dict:
+        """Block until the simulation reaches a terminal state (or the deadline)."""
+        start = time.monotonic()
+        while True:
+            sim = self.get_simulation(sim_id)
+            state = (sim.get("state") or "").lower()
+            if state in _TERMINAL:
+                return sim
+            if deadline is not None and time.monotonic() - start > deadline:
+                raise TimeoutError(f"simulation {sim_id} still {state!r} after {deadline}s")
+            time.sleep(poll)
+
+    # -- batches ---------------------------------------------------------------
+
+    def submit_batch(
+        self,
+        *,
+        engine_version: str,
+        weather: Union[str, ArtifactRef],
+        variants: Sequence[Union[Variant, dict]],
+        priority: Optional[int] = None,
+        max_parallelism: Optional[int] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> dict:
+        """POST /v1/batches → ``{batchId, state:"expanding"}`` (CONTRACT §3)."""
+        body: dict = {
+            "engineVersion": engine_version,
+            "weather": as_ref(weather),
+            "variants": [v.to_dict() if isinstance(v, Variant) else v for v in variants],
+        }
+        if priority is not None:
+            body["priority"] = priority
+        if max_parallelism is not None:
+            body["maxParallelism"] = max_parallelism
+        if idempotency_key is not None:
+            body["idempotencyKey"] = idempotency_key
+
+        resp = self._session.post(
+            f"{self.base_url}/v1/batches", json=body, timeout=self.timeout
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def get_batch(self, batch_id: str) -> dict:
+        """GET /v1/batches/{id} → ``{id, state, total, succeeded, failed}``."""
+        resp = self._session.get(
+            f"{self.base_url}/v1/batches/{batch_id}", timeout=self.timeout
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def list_batch_simulations(self, batch_id: str, *, limit: int = 100, offset: int = 0) -> dict:
+        """GET /v1/batches/{id}/simulations → ``{items:[...], total}``."""
+        resp = self._session.get(
+            f"{self.base_url}/v1/batches/{batch_id}/simulations",
+            params={"limit": limit, "offset": offset},
+            timeout=self.timeout,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    # -- input upload convenience ---------------------------------------------
+
+    def upload_input(
+        self,
+        local_path: str,
+        ref: str,
+        *,
+        s3_endpoint: Optional[str] = None,
+        s3_region: str = "us-east-1",
+        s3_access_key: Optional[str] = None,
+        s3_secret_key: Optional[str] = None,
+    ) -> ArtifactRef:
+        """Upload a local model/weather file to ``ref`` (``s3://bucket/key``) via
+        boto3 and return an :class:`ArtifactRef` carrying its sha256.
+
+        boto3 is imported lazily so the rest of the SDK has no hard dependency.
+        """
+        import boto3  # lazy
+
+        parsed = urlparse(ref)
+        if parsed.scheme != "s3":
+            raise ValueError(f"upload_input requires an s3:// ref, got {ref!r}")
+        bucket, key = parsed.netloc, parsed.path.lstrip("/")
+
+        client = boto3.client(
+            "s3",
+            endpoint_url=s3_endpoint,
+            region_name=s3_region,
+            aws_access_key_id=s3_access_key,
+            aws_secret_access_key=s3_secret_key,
+        )
+        client.upload_file(local_path, bucket, key)
+        return ArtifactRef(ref=ref, sha256=sha256_file(local_path))

synergyplus/models.py

@@ -0,0 +1,60 @@
+"""Lightweight request/response models for the SynergyPlus API (CONTRACT §3)."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from dataclasses import dataclass
+from typing import Optional, Union
+
+
+@dataclass
+class ArtifactRef:
+    """A model or weather blob in object storage (``s3://bucket/key``).
+
+    ``sha256`` feeds the deterministic content hash (CONTRACT §2.1). If you have
+    the local file, use :meth:`from_file` to compute it.
+    """
+
+    ref: str
+    sha256: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        d = {"ref": self.ref}
+        if self.sha256:
+            d["sha256"] = self.sha256
+        return d
+
+    @classmethod
+    def from_file(cls, ref: str, local_path: str) -> "ArtifactRef":
+        """Build a ref whose sha256 is hashed from a local copy of the object."""
+        return cls(ref=ref, sha256=sha256_file(local_path))
+
+
+def sha256_file(path: str) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(1024 * 1024), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def as_ref(value: Union[str, ArtifactRef], sha256: Optional[str] = None) -> dict:
+    """Accept either a bare ``s3://`` string or an :class:`ArtifactRef`."""
+    if isinstance(value, ArtifactRef):
+        return value.to_dict()
+    return ArtifactRef(ref=value, sha256=sha256).to_dict()
+
+
+@dataclass
+class Variant:
+    """One model variant in a batch submission."""
+
+    model: Union[str, ArtifactRef]
+    name: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        d: dict = {"model": as_ref(self.model)}
+        if self.name:
+            d["name"] = self.name
+        return d

synergyplus-0.2.0.dist-info/METADATA

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: synergyplus
+Version: 0.2.0
+Summary: Python client for the SynergyPlus distributed EnergyPlus runner.
+Author-email: SynergyPlus contributors <tanryan777@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/City-Syntax/SynergyPlus
+Project-URL: Repository, https://github.com/City-Syntax/SynergyPlus
+Project-URL: Issues, https://github.com/City-Syntax/SynergyPlus/issues
+Keywords: energyplus,simulation,building-energy,sdk,client
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Provides-Extra: s3
+Requires-Dist: boto3>=1.34; extra == "s3"
+Dynamic: license-file
+
+# SynergyPlus Python SDK
+
+`synergyplus` is the official Python client for the [SynergyPlus](https://github.com/City-Syntax/SynergyPlus)
+distributed EnergyPlus runner. It wraps the apiserver's HTTP API for submitting
+simulations and parametric batches, polling their state, and fetching results.
+
+## Install
+
+```bash
+pip install synergyplus
+
+# Optional: enable SynergyClient.upload_input() for pushing local model/weather
+# files to S3-compatible storage (MinIO, AWS S3, ...).
+pip install "synergyplus[s3]"
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+```python
+from synergyplus import SynergyClient, ArtifactRef
+
+sp = SynergyClient("http://localhost:8090", token="synergy-dev-key")
+
+sim = sp.submit_simulation(
+    engine_version="24.1.0",
+    model=ArtifactRef("s3://models/sample/baseline.idf"),
+    weather=ArtifactRef("s3://weather/sample/chicago.epw"),
+)
+
+sp.wait(sim["id"])
+print(sp.get_results(sim["id"]))
+```
+
+## API
+
+### `SynergyClient(base_url, token=None, timeout=30.0)`
+
+| Method | Description |
+| --- | --- |
+| `healthz()` | `GET /healthz` — returns `True` if the apiserver is up. |
+| `submit_simulation(*, engine_version, model, weather, priority=None, extraction_spec=None)` | `POST /v1/simulations` → `{id, state}`. |
+| `get_simulation(sim_id)` | `GET /v1/simulations/{id}` → `{id, state, verdict?, result?}`. |
+| `get_results(sim_id)` | `GET /v1/results/{simId}` → `{verdict, metrics, artifactUri}`. |
+| `wait(sim_id, *, poll=2.0, deadline=None)` | Block until the simulation reaches a terminal state (`succeeded`/`failed`). |
+| `submit_batch(*, engine_version, weather, variants, priority=None, max_parallelism=None, idempotency_key=None)` | `POST /v1/batches` → `{batchId, state}`. |
+| `get_batch(batch_id)` | `GET /v1/batches/{id}` → `{id, state, total, succeeded, failed}`. |
+| `list_batch_simulations(batch_id, *, limit=100, offset=0)` | `GET /v1/batches/{id}/simulations` → `{items, total}`. |
+| `upload_input(local_path, ref, *, s3_endpoint=None, s3_region="us-east-1", s3_access_key=None, s3_secret_key=None)` | Upload a local file to an `s3://` ref and return an `ArtifactRef` with its sha256. Requires the `s3` extra. |
+
+`model`/`weather` accept either an `s3://...` string or an `ArtifactRef`.
+
+### Batch example
+
+```python
+from synergyplus import SynergyClient, ArtifactRef, Variant
+
+sp = SynergyClient("http://localhost:8090", token="synergy-dev-key")
+
+batch = sp.submit_batch(
+    engine_version="24.1.0",
+    weather=ArtifactRef("s3://weather/sample/chicago.epw"),
+    variants=[
+        Variant(model=ArtifactRef("s3://models/a.idf")),
+        Variant(model=ArtifactRef("s3://models/b.idf")),
+    ],
+    max_parallelism=8,
+)
+print(batch["batchId"])
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

synergyplus-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+synergyplus/__init__.py,sha256=b_d5ZIr40AQXGWumbMxsrWvY7Jz-6jpqaKk-E30-s_s,614
+synergyplus/client.py,sha256=ksvAPtOSjjVu68A8lKAhf9nGD2esj_3OgdcJjsk70No,6443
+synergyplus/models.py,sha256=Uqax7kvoS9xcbhxOQ_hBAaDXE3Sex5oHV3kVHOMXVnk,1679
+synergyplus-0.2.0.dist-info/licenses/LICENSE,sha256=-9yfoYht3-ACJL7nob2B0jG6wNGKystmQB0LyiZVetA,1081
+synergyplus-0.2.0.dist-info/METADATA,sha256=lK05iJPnO6F2QN98PNuvaSZNOC2urvPOX8Cwhqp5x7o,3781
+synergyplus-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+synergyplus-0.2.0.dist-info/top_level.txt,sha256=TOz0-oSkw_Ql2Xccr7XlImMAWqGD91hDEACFqH1LyhA,12
+synergyplus-0.2.0.dist-info/RECORD,,

synergyplus-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

synergyplus-0.2.0.dist-info/licenses/LICENSE

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

synergyplus-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+synergyplus