simudyne-pulse 0.6.0__py3-none-any.whl

simudyne/__init__.py

@@ -0,0 +1,3 @@
+from simudyne.client import PulseABM, PulseAPIError
+
+__all__ = ["PulseABM", "PulseAPIError"]

simudyne/client.py

@@ -0,0 +1,121 @@
+import os
+import sys
+import time
+import requests
+import io
+import polars as pl
+from tqdm import tqdm
+import tempfile
+import math
+
+from simudyne.exceptions import PulseAPIError
+
+
+class PulseABM:
+    DEFAULT_BASE_URL = "https://pulse-api.simudyne.com"
+    DEFAULT_TIMEOUT = 30
+    RETRYABLE_STATUS_CODES = {429, 502, 503, 504}
+
+    def __init__(
+        self,
+        api_key: str = None,
+        base_url: str = None,
+        timeout: int = None,
+        max_retries: int = 3,
+    ):
+        self.api_key = api_key or os.getenv("SIMUDYNE_API_KEY")
+        if not self.api_key:
+            raise ValueError("SIMUDYNE_API_KEY is not set -> pass api_key or set SIMUDYNE_API_KEY in environment")
+        self.base_url = base_url or os.getenv("SIMUDYNE_BASE_URL", self.DEFAULT_BASE_URL)
+        self.timeout = timeout or self.DEFAULT_TIMEOUT
+        self.max_retries = max_retries
+        self.session = requests.Session()
+        self.session.headers.update({"X-API-Key": self.api_key})
+        self.session.verify = True
+
+        from simudyne.resources.profile import ProfileResource
+        from simudyne.resources.api_keys import ApiKeysResource
+        from simudyne.resources.data import DataResource
+        from simudyne.resources.simulation import SimulationResource
+        from simudyne.resources.simulator_gym import SimulatorGymResource
+        from simudyne.resources.validation import ValidationResource
+
+        self.profile = ProfileResource(self)
+        self.api_keys = ApiKeysResource(self)
+        self.data = DataResource(self)
+        self.simulation = SimulationResource(self)
+        self.simulator_gym = SimulatorGymResource(self)
+        self.validation = ValidationResource(self)
+
+    def _request_with_retries(self, method: str, url: str, **kwargs):
+        """Execute request with timeout and exponential backoff for transient errors."""
+        kwargs.setdefault("timeout", self.timeout)
+        last_exception = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self.session.request(method, url, **kwargs)
+
+                if response.ok:
+                    return response
+
+                if response.status_code in self.RETRYABLE_STATUS_CODES and attempt < self.max_retries:
+                    delay = 2 ** attempt
+                    time.sleep(delay)
+                    continue
+
+                try:
+                    detail = response.json().get("detail", response.text)
+                except ValueError:
+                    detail = response.text
+                raise PulseAPIError(response.status_code, detail)
+
+            except (requests.exceptions.Timeout, requests.exceptions.ConnectionError) as e:
+                last_exception = e
+                if attempt < self.max_retries:
+                    delay = 2 ** attempt
+                    time.sleep(delay)
+                    continue
+                raise
+
+        raise last_exception
+
+    def _request(self, method: str, endpoint: str, **kwargs):
+        url = f"{self.base_url}{endpoint}"
+        response = self._request_with_retries(method, url, **kwargs)
+        return response.json()
+    
+    def _request_csv(self, method, endpoint, **kwargs):
+        PAGE_SIZE = 100000
+        params = kwargs.get("params", {})
+
+        params["limit"] = PAGE_SIZE
+        params["offset"] = 0
+        kwargs["params"] = params
+
+        url = f"{self.base_url}{endpoint}"
+        response = self._request_with_retries(method, url, **kwargs)
+
+        total_rows = int(response.headers.get("X-Total-Rows", 0))
+        total_pages = math.ceil(total_rows / PAGE_SIZE) if total_rows > 0 else 1
+
+        frames = []
+        df = pl.read_csv(response.text.encode(), infer_schema_length=10000)
+        frames.append(df)
+        schema = df.schema
+
+        if total_pages > 1:
+            with tqdm(total=total_pages, initial=1, unit="page", desc=f"Downloading ({total_rows:,} rows)") as pbar:
+                for page in range(1, total_pages):
+                    params["offset"] = page * PAGE_SIZE
+                    kwargs["params"] = params
+                    response = self._request_with_retries(method, url, **kwargs)
+                    df = pl.read_csv(response.text.encode(), schema_overrides=schema, infer_schema_length=10000)
+                    if df.is_empty():
+                        break
+                    frames.append(df)
+                    pbar.update(1)
+
+        result = pl.concat(frames) if len(frames) > 1 else frames[0]
+        print(f"Done: {result.shape[0]:,} rows, {result.shape[1]} columns", file=sys.stderr)
+        return result

simudyne/exceptions.py

@@ -0,0 +1,7 @@
+class PulseAPIError(Exception):
+    """Exception raised for Pulse API errors."""
+
+    def __init__(self, status_code: int, detail: str):
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"API Error ({status_code}): {detail}")

simudyne/resources/api_keys.py

@@ -0,0 +1,12 @@
+class ApiKeysResource:
+    def __init__(self, client):
+        self._client = client
+    
+    def create(self, name: str):
+        return self._client._request("POST", "/api-keys", json={"name": name})
+    
+    def list(self):
+        return self._client._request("GET", "/api-keys")
+    
+    def revoke(self, key_id: str):
+        return self._client._request("DELETE", f"/api-keys/{key_id}")

simudyne/resources/data.py

@@ -0,0 +1,45 @@
+AVAILABLE_SYMBOLS_PATH = "/data/available-symbols"
+
+
+class DataResource:
+    def __init__(self, client):
+        self._client = client
+
+    def get_available_symbols(
+        self,
+        symbol: str | None = None,
+        exchange: str | None = None,
+        provider: str | None = None,
+        date: str | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+    ):
+        """List calibrated instruments and the dates available for each.
+
+        All arguments are optional filters; with none passed the whole catalog
+        comes back, as before.
+
+        Args:
+            symbol: Exact symbol, e.g. "700.HK".
+            exchange: Exchange protocol, e.g. "hkex_securities".
+            provider: Data provider, e.g. "omd" or "bmll".
+            date: Calibration date "YYYY-MM-DD". Keeps only instruments
+                  calibrated on that date, and narrows each instrument's
+                  available_dates to it.
+            limit: Max instruments to return.
+            offset: Instruments to skip (for paging alongside limit).
+
+        Returns:
+            list of instrument dicts, each with available_dates.
+        """
+        params = {
+            k: v for k, v in {
+                "symbol": symbol,
+                "exchange": exchange,
+                "provider": provider,
+                "date": date,
+                "limit": limit,
+                "offset": offset,
+            }.items() if v is not None
+        }
+        return self._client._request("GET", AVAILABLE_SYMBOLS_PATH, params=params or None)

simudyne/resources/historical.py

@@ -0,0 +1 @@
+# Historical endpoints have been removed. Use data.get_available() instead.

simudyne/resources/profile.py

@@ -0,0 +1,30 @@
+class ProfileResource:
+    def __init__(self, client):
+        self._client = client
+
+    def get(self):
+        return self._client._request("GET", "/profile")
+    
+    def usage(self):
+        return self._client._request("GET", "/profile/usage")
+
+    def downloads(self):
+        """Download quota usage for the current rolling 24-hour window.
+
+        Returns a dict with ``limit``, ``used``, ``remaining``,
+        ``window_hours`` and ``downloaded_groups``. ``limit`` and
+        ``remaining`` are ``None`` on the pro and demo tiers (unlimited); on
+        the free tier they reflect the account's daily download allowance.
+
+        A "download" is one simulation group (all Monte Carlo runs of one
+        scenario). ``used`` counts NEW groups added in the window;
+        ``downloaded_groups`` lists every group you have ever downloaded —
+        membership is permanent, so those are free to re-fetch forever in any
+        run or file format.
+
+        Example:
+            >>> quota = client.profile.downloads()
+            >>> print(f"{quota['used']}/{quota['limit']} used, {quota['remaining']} left")
+            >>> print(f"{len(quota['downloaded_groups'])} groups owned")
+        """
+        return self._client._request("GET", "/profile/downloads")