simudyne-pulse 0.6.0__tar.gz

simudyne_pulse-0.6.0/LICENSE

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

simudyne_pulse-0.6.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: simudyne-pulse
+Version: 0.6.0
+Summary: Python SDK for the Simudyne Pulse synthetic market data API
+Author-email: Simudyne <support@simudyne.com>
+License-Expression: MIT
+Project-URL: Homepage, https://pulse.simudyne.com
+Project-URL: Documentation, https://pulse.simudyne.com/docs
+Project-URL: Repository, https://github.com/simudyne/pulse-api
+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: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: polars>=0.20.0
+Requires-Dist: tqdm>=4.60.0
+Requires-Dist: websocket-client>=1.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Dynamic: license-file
+
+# Simudyne Pulse Python SDK
+
+Python client for the [Pulse](https://pulse.simudyne.com) synthetic market data API. Returns data as [Polars](https://pola.rs/) DataFrames.
+
+## Installation
+
+```bash
+pip install simudyne-pulse
+```
+
+The distribution is named `simudyne-pulse`; the import name is `simudyne`:
+
+```python
+from simudyne import PulseABM
+```
+
+Requires Python 3.10+.
+
+### Development builds
+
+The `dev` branch is a prerelease channel. Pushes to it publish prerelease
+versions (e.g. `0.6.0.dev1`) that are separate from the stable versions cut on
+`prod`. `pip install simudyne-pulse` always resolves to the latest **stable**
+release and ignores prereleases, so dev builds can never affect a normal
+install.
+
+To install the latest dev build, opt in with `--pre`:
+
+```bash
+pip install --pre simudyne-pulse
+```
+
+Only use dev builds for testing unreleased changes; they are not guaranteed
+stable. Merge `dev` into `prod` to promote those changes to a stable release.
+
+## Quick start
+
+```python
+from simudyne import PulseABM
+
+client = PulseABM(api_key="pk_live_...")
+
+# List available exchanges, symbols, and dates
+symbols = client.data.get_symbols(year=2024)
+print(symbols)
+
+# Fetch L2 order book data
+df = client.data.get_L2("HKEX", "HSIJ4", "2024-04-02T09:15:00", "2024-04-02T09:16:00")
+print(df.head())
+```
+
+## API reference
+
+### `PulseABM(api_key, base_url=None)`
+
+| Parameter | Env variable | Default |
+|-----------|-------------|---------|
+| `api_key` | `SIMUDYNE_API_KEY` | required |
+| `base_url` | `SIMUDYNE_BASE_URL` | Pulse API |
+
+### `client.data`
+
+All data methods return Polars DataFrames. Large result sets are automatically paginated.
+
+```python
+# Available exchanges, symbols, and dates
+client.data.get_symbols(year=2024)
+
+# L1: top of book (best bid/ask)
+client.data.get_L1("HKEX", "HSIJ4", "2024-04-02T09:15:00", "2024-04-02T10:00:00")
+
+# L2: full order book (all levels)
+client.data.get_L2("HKEX", "HSIJ4", "2024-04-02T09:15:00", "2024-04-02T09:16:00")
+
+# Orders: individual order events
+client.data.get_orders("HKEX", "HSIJ4", "2024-04-02T09:15:00", "2024-04-02T10:00:00")
+
+# Trades: executed trades
+client.data.get_trades("HKEX", "HSIJ4", "2024-04-02T09:15:00", "2024-04-02T10:00:00")
+```
+
+**Parameters** (same for all data methods):
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `exchange` | str | Exchange code (e.g. `HKEX`) |
+| `sym` | str | Symbol name (e.g. `HSIJ4`) |
+| `datetime_start` | str | Start time, ISO 8601 (e.g. `2024-04-02T09:15:00`) |
+| `datetime_end` | str | End time, ISO 8601 |
+
+### `client.profile`
+
+```python
+client.profile.get()      # Account info
+client.profile.usage()    # API usage stats
+```
+
+### `client.api_keys`
+
+```python
+client.api_keys.list()                    # List active keys
+client.api_keys.create(name="research")   # Create a new key
+client.api_keys.revoke(key_id="key_...")  # Revoke a key
+```
+
+## Configuration
+
+You can set your API key as an environment variable instead of passing it directly:
+
+```bash
+export SIMUDYNE_API_KEY=pk_live_...
+```
+
+```python
+from simudyne import PulseABM
+client = PulseABM()  # picks up SIMUDYNE_API_KEY automatically
+```
+
+## License
+
+MIT

simudyne_pulse-0.6.0/README.md

@@ -0,0 +1,121 @@
+# Simudyne Pulse Python SDK
+
+Python client for the [Pulse](https://pulse.simudyne.com) synthetic market data API. Returns data as [Polars](https://pola.rs/) DataFrames.
+
+## Installation
+
+```bash
+pip install simudyne-pulse
+```
+
+The distribution is named `simudyne-pulse`; the import name is `simudyne`:
+
+```python
+from simudyne import PulseABM
+```
+
+Requires Python 3.10+.
+
+### Development builds
+
+The `dev` branch is a prerelease channel. Pushes to it publish prerelease
+versions (e.g. `0.6.0.dev1`) that are separate from the stable versions cut on
+`prod`. `pip install simudyne-pulse` always resolves to the latest **stable**
+release and ignores prereleases, so dev builds can never affect a normal
+install.
+
+To install the latest dev build, opt in with `--pre`:
+
+```bash
+pip install --pre simudyne-pulse
+```
+
+Only use dev builds for testing unreleased changes; they are not guaranteed
+stable. Merge `dev` into `prod` to promote those changes to a stable release.
+
+## Quick start
+
+```python
+from simudyne import PulseABM
+
+client = PulseABM(api_key="pk_live_...")
+
+# List available exchanges, symbols, and dates
+symbols = client.data.get_symbols(year=2024)
+print(symbols)
+
+# Fetch L2 order book data
+df = client.data.get_L2("HKEX", "HSIJ4", "2024-04-02T09:15:00", "2024-04-02T09:16:00")
+print(df.head())
+```
+
+## API reference
+
+### `PulseABM(api_key, base_url=None)`
+
+| Parameter | Env variable | Default |
+|-----------|-------------|---------|
+| `api_key` | `SIMUDYNE_API_KEY` | required |
+| `base_url` | `SIMUDYNE_BASE_URL` | Pulse API |
+
+### `client.data`
+
+All data methods return Polars DataFrames. Large result sets are automatically paginated.
+
+```python
+# Available exchanges, symbols, and dates
+client.data.get_symbols(year=2024)
+
+# L1: top of book (best bid/ask)
+client.data.get_L1("HKEX", "HSIJ4", "2024-04-02T09:15:00", "2024-04-02T10:00:00")
+
+# L2: full order book (all levels)
+client.data.get_L2("HKEX", "HSIJ4", "2024-04-02T09:15:00", "2024-04-02T09:16:00")
+
+# Orders: individual order events
+client.data.get_orders("HKEX", "HSIJ4", "2024-04-02T09:15:00", "2024-04-02T10:00:00")
+
+# Trades: executed trades
+client.data.get_trades("HKEX", "HSIJ4", "2024-04-02T09:15:00", "2024-04-02T10:00:00")
+```
+
+**Parameters** (same for all data methods):
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `exchange` | str | Exchange code (e.g. `HKEX`) |
+| `sym` | str | Symbol name (e.g. `HSIJ4`) |
+| `datetime_start` | str | Start time, ISO 8601 (e.g. `2024-04-02T09:15:00`) |
+| `datetime_end` | str | End time, ISO 8601 |
+
+### `client.profile`
+
+```python
+client.profile.get()      # Account info
+client.profile.usage()    # API usage stats
+```
+
+### `client.api_keys`
+
+```python
+client.api_keys.list()                    # List active keys
+client.api_keys.create(name="research")   # Create a new key
+client.api_keys.revoke(key_id="key_...")  # Revoke a key
+```
+
+## Configuration
+
+You can set your API key as an environment variable instead of passing it directly:
+
+```bash
+export SIMUDYNE_API_KEY=pk_live_...
+```
+
+```python
+from simudyne import PulseABM
+client = PulseABM()  # picks up SIMUDYNE_API_KEY automatically
+```
+
+## License
+
+MIT

simudyne_pulse-0.6.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "simudyne-pulse"
+version = "0.6.0"
+description = "Python SDK for the Simudyne Pulse synthetic market data API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Simudyne", email = "support@simudyne.com" },
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "requests>=2.28.0",
+    "polars>=0.20.0",
+    "tqdm>=4.60.0",
+    "websocket-client>=1.0.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8.0.0"]
+
+[project.urls]
+Homepage = "https://pulse.simudyne.com"
+Documentation = "https://pulse.simudyne.com/docs"
+Repository = "https://github.com/simudyne/pulse-api"
+
+
+
+
+
+
+
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+changelog_file = "CHANGELOG.md"
+build_command = "pip install build && python -m build"
+
+# Release channels. `prod` cuts stable versions (0.6.0); `dev` cuts
+# prereleases (0.6.0-dev.1). Prerelease tags never collide with stable ones,
+# and `pip install git+...@dev` is how you pull a dev build.
+[tool.semantic_release.branches.prod]
+match = "prod"
+prerelease = false
+
+[tool.semantic_release.branches.dev]
+match = "dev"
+prerelease = true
+prerelease_token = "dev"

simudyne_pulse-0.6.0/setup.cfg

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

simudyne_pulse-0.6.0/src/simudyne/__init__.py

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

simudyne_pulse-0.6.0/src/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_pulse-0.6.0/src/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_pulse-0.6.0/src/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_pulse-0.6.0/src/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_pulse-0.6.0/src/simudyne/resources/historical.py

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

simudyne_pulse-0.6.0/src/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")