epic-elios-client 1.0.0__tar.gz

epic_elios_client-1.0.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: epic-elios-client
+Version: 1.0.0
+Summary: Participant SDK for the EPIC — ELIOS Predictive Intelligence Challenge platform.
+Author: ELIOS Lab
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: websockets
+Provides-Extra: notebook
+Requires-Dist: pandas; extra == "notebook"
+
+# EPIC Participant SDK
+
+`epic-elios-client` is the participant SDK for the EPIC — ELIOS Predictive Intelligence Challenge platform. It helps students and competitors authenticate, browse contests, collect live observations, submit predictions, and inspect results from the default EPIC server at <https://epic.elioslab.net>.
+
+## Installation
+
+Install the SDK:
+
+```bash
+pip install epic-elios-client
+```
+
+Install the SDK with notebook extras for the Jupyter quickstart:
+
+```bash
+pip install "epic-elios-client[notebook]"
+```
+
+## Minimal Usage
+
+```python
+import asyncio
+
+from epic_client import EPICClient
+
+
+async def main():
+    client = EPICClient("https://epic.elioslab.net")
+    client.login("student1", "correct-password")
+
+    contests = client.list_contests(status="ACTIVE")
+    contest_id = contests[0]["contest_id"]
+
+    observations = await client.collect(contest_id, duration_seconds=10)
+    latest = observations[-1]
+
+    submission = client.submit(
+        contest_id=contest_id,
+        task_id="forecasting",
+        prediction_from_sequence=latest["sequence_id"],
+        payload={
+            "forecast": {
+                "horizon_1": latest["sensors"],
+                "horizon_5": latest["sensors"],
+                "horizon_10": latest["sensors"],
+            }
+        },
+    )
+    print(submission)
+
+
+asyncio.run(main())
+```

epic_elios_client-1.0.0/README.md

@@ -0,0 +1,53 @@
+# EPIC Participant SDK
+
+`epic-elios-client` is the participant SDK for the EPIC — ELIOS Predictive Intelligence Challenge platform. It helps students and competitors authenticate, browse contests, collect live observations, submit predictions, and inspect results from the default EPIC server at <https://epic.elioslab.net>.
+
+## Installation
+
+Install the SDK:
+
+```bash
+pip install epic-elios-client
+```
+
+Install the SDK with notebook extras for the Jupyter quickstart:
+
+```bash
+pip install "epic-elios-client[notebook]"
+```
+
+## Minimal Usage
+
+```python
+import asyncio
+
+from epic_client import EPICClient
+
+
+async def main():
+    client = EPICClient("https://epic.elioslab.net")
+    client.login("student1", "correct-password")
+
+    contests = client.list_contests(status="ACTIVE")
+    contest_id = contests[0]["contest_id"]
+
+    observations = await client.collect(contest_id, duration_seconds=10)
+    latest = observations[-1]
+
+    submission = client.submit(
+        contest_id=contest_id,
+        task_id="forecasting",
+        prediction_from_sequence=latest["sequence_id"],
+        payload={
+            "forecast": {
+                "horizon_1": latest["sensors"],
+                "horizon_5": latest["sensors"],
+                "horizon_10": latest["sensors"],
+            }
+        },
+    )
+    print(submission)
+
+
+asyncio.run(main())
+```

epic_elios_client-1.0.0/epic_client/__init__.py

@@ -0,0 +1,5 @@
+"""EPIC Participant SDK."""
+
+from epic_client.client import EPICClient
+
+__all__ = ["EPICClient"]

epic_elios_client-1.0.0/epic_client/client.py

@@ -0,0 +1,199 @@
+"""Participant client for EPIC contests."""
+
+from __future__ import annotations
+
+import asyncio
+import csv
+import json
+import time
+from pathlib import Path
+from typing import AsyncIterator
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode, urljoin, urlparse, urlunparse
+from urllib.request import Request, urlopen
+
+
+class EPICClient:
+    def __init__(self, server_url: str = "https://epic.elioslab.net") -> None:
+        self.server_url = server_url.rstrip("/") + "/"
+        self._token: str | None = None
+
+    def login(self, username: str, password: str) -> dict:
+        response = self._request(
+            "POST",
+            "/api/v1/auth/login",
+            {"username": username, "password": password},
+            authenticated=False,
+        )
+        self._token = response["access_token"]
+        return response
+
+    def register(self, contest_id: str) -> dict:
+        try:
+            return self._request(
+                "POST",
+                "/api/v1/contest-registrations",
+                {"contest_id": contest_id},
+            )
+        except RuntimeError as exc:
+            if "Already registered for this contest" not in str(exc):
+                raise
+            return {
+                "contest_id": contest_id,
+                "status": "REGISTERED",
+                "message": "Already registered for this contest",
+            }
+
+    def list_contests(self, status: str | None = None) -> list[dict]:
+        query = f"?{urlencode({'status': status})}" if status is not None else ""
+        response = self._request("GET", f"/api/v1/contests{query}")
+        contests = response["contests"]
+        for contest in contests:
+            if "contest_id" not in contest and "id" in contest:
+                contest["contest_id"] = contest["id"]
+        return contests
+
+    async def stream(self, contest_id: str) -> AsyncIterator[dict]:
+        self._require_token()
+        websocket_url = self._websocket_url(f"/api/v1/ws/contests/{contest_id}")
+        reconnect_delay = 1.0
+
+        while True:
+            try:
+                import websockets
+
+                async with websockets.connect(websocket_url) as websocket:
+                    async for message in websocket:
+                        payload = json.loads(message)
+                        yield {
+                            "sequence_id": payload["sequence_id"],
+                            "timestamp": payload["timestamp"],
+                            "sensors": payload["sensors"],
+                        }
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                await asyncio.sleep(reconnect_delay)
+
+    async def collect(
+        self,
+        contest_id: str,
+        duration_seconds: float,
+        csv_path: str | Path | None = None,
+    ) -> list[dict]:
+        observations: list[dict] = []
+        deadline = time.monotonic() + duration_seconds
+        writer = None
+        csv_file = None
+
+        if csv_path is not None:
+            csv_file = Path(csv_path).open("w", newline="")
+            writer = csv.DictWriter(
+                csv_file,
+                fieldnames=["sequence_id", "timestamp", "sensors"],
+            )
+            writer.writeheader()
+
+        try:
+            stream = self.stream(contest_id).__aiter__()
+            while True:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    break
+                try:
+                    observation = await asyncio.wait_for(stream.__anext__(), remaining)
+                except asyncio.TimeoutError:
+                    break
+                observations.append(observation)
+                if writer is not None:
+                    writer.writerow(
+                        {
+                            "sequence_id": observation["sequence_id"],
+                            "timestamp": observation["timestamp"],
+                            "sensors": json.dumps(observation["sensors"]),
+                        }
+                    )
+        finally:
+            if csv_file is not None:
+                csv_file.close()
+
+        return observations
+
+    def submit(
+        self,
+        contest_id: str,
+        task_id: str,
+        prediction_from_sequence: int,
+        payload: dict,
+    ) -> dict:
+        return self._request(
+            "POST",
+            f"/api/v1/contests/{contest_id}/submissions",
+            {
+                "task_id": task_id,
+                "prediction_from_sequence": prediction_from_sequence,
+                "payload": payload,
+            },
+        )
+
+    def get_scores(self, contest_id: str) -> dict:
+        submissions = self._request(
+            "GET", f"/api/v1/contests/{contest_id}/submissions"
+        )["submissions"]
+        scored_submissions = []
+        for submission in submissions:
+            scores = self._request(
+                "GET", f"/api/v1/submissions/{submission['submission_id']}/scores"
+            )
+            scored_submissions.append({**submission, "scores": scores["scores"]})
+        return {"contest_id": contest_id, "submissions": scored_submissions}
+
+    def get_leaderboard(self, contest_id: str) -> dict:
+        return self._request("GET", f"/api/v1/contests/{contest_id}/leaderboard")
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: dict | None = None,
+        authenticated: bool = True,
+    ) -> dict:
+        if authenticated:
+            self._require_token()
+
+        data = None
+        headers = {"Content-Type": "application/json"}
+        if authenticated and self._token is not None:
+            headers["Authorization"] = f"Bearer {self._token}"
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+
+        request = Request(
+            urljoin(self.server_url, path.lstrip("/")),
+            data=data,
+            headers=headers,
+            method=method,
+        )
+        try:
+            with urlopen(request) as response:
+                response_body = response.read()
+        except HTTPError as exc:
+            message = exc.read().decode("utf-8")
+            raise RuntimeError(f"EPIC API request failed: {exc.code} {message}") from exc
+        except URLError as exc:
+            raise RuntimeError(f"EPIC API request failed: {exc.reason}") from exc
+
+        if not response_body:
+            return {}
+        return json.loads(response_body.decode("utf-8"))
+
+    def _require_token(self) -> None:
+        if self._token is None:
+            raise RuntimeError("Not authenticated. Call login() first.")
+
+    def _websocket_url(self, path: str) -> str:
+        self._require_token()
+        parsed = urlparse(urljoin(self.server_url, path.lstrip("/")))
+        scheme = "wss" if parsed.scheme == "https" else "ws"
+        query = urlencode({"token": self._token})
+        return urlunparse((scheme, parsed.netloc, parsed.path, "", query, ""))

epic_elios_client-1.0.0/epic_elios_client.egg-info/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: epic-elios-client
+Version: 1.0.0
+Summary: Participant SDK for the EPIC — ELIOS Predictive Intelligence Challenge platform.
+Author: ELIOS Lab
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: websockets
+Provides-Extra: notebook
+Requires-Dist: pandas; extra == "notebook"
+
+# EPIC Participant SDK
+
+`epic-elios-client` is the participant SDK for the EPIC — ELIOS Predictive Intelligence Challenge platform. It helps students and competitors authenticate, browse contests, collect live observations, submit predictions, and inspect results from the default EPIC server at <https://epic.elioslab.net>.
+
+## Installation
+
+Install the SDK:
+
+```bash
+pip install epic-elios-client
+```
+
+Install the SDK with notebook extras for the Jupyter quickstart:
+
+```bash
+pip install "epic-elios-client[notebook]"
+```
+
+## Minimal Usage
+
+```python
+import asyncio
+
+from epic_client import EPICClient
+
+
+async def main():
+    client = EPICClient("https://epic.elioslab.net")
+    client.login("student1", "correct-password")
+
+    contests = client.list_contests(status="ACTIVE")
+    contest_id = contests[0]["contest_id"]
+
+    observations = await client.collect(contest_id, duration_seconds=10)
+    latest = observations[-1]
+
+    submission = client.submit(
+        contest_id=contest_id,
+        task_id="forecasting",
+        prediction_from_sequence=latest["sequence_id"],
+        payload={
+            "forecast": {
+                "horizon_1": latest["sensors"],
+                "horizon_5": latest["sensors"],
+                "horizon_10": latest["sensors"],
+            }
+        },
+    )
+    print(submission)
+
+
+asyncio.run(main())
+```

epic_elios_client-1.0.0/epic_elios_client.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+epic_client/__init__.py
+epic_client/client.py
+epic_elios_client.egg-info/PKG-INFO
+epic_elios_client.egg-info/SOURCES.txt
+epic_elios_client.egg-info/dependency_links.txt
+epic_elios_client.egg-info/requires.txt
+epic_elios_client.egg-info/top_level.txt

epic_elios_client-1.0.0/epic_elios_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

epic_elios_client-1.0.0/epic_elios_client.egg-info/requires.txt

@@ -0,0 +1,4 @@
+websockets
+
+[notebook]
+pandas

epic_elios_client-1.0.0/epic_elios_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+epic_client

epic_elios_client-1.0.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "epic-elios-client"
+version = "1.0.0"
+description = "Participant SDK for the EPIC — ELIOS Predictive Intelligence Challenge platform."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+  { name = "ELIOS Lab" }
+]
+license = { text = "MIT" }
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "License :: OSI Approved :: MIT License",
+  "Intended Audience :: Education",
+  "Intended Audience :: Science/Research",
+]
+dependencies = [
+  "websockets",
+]
+
+[project.optional-dependencies]
+notebook = [
+  "pandas",
+]
+
+[tool.setuptools]
+packages = ["epic_client"]

epic_elios_client-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+