simudyne-pulse 0.6.0.dev1__py3-none-any.whl

simudyne/resources/simulator_gym.py

@@ -0,0 +1,118 @@
+import json
+
+import websocket
+
+
+class GymSession:
+    """A live connection to a Pulse simulator-gym environment session."""
+
+    def __init__(self, ws: websocket.WebSocket, session_id: str):
+        self._ws = ws
+        self.session_id = session_id
+
+    def reset(self, seed: int = None) -> dict:
+        """Reset the environment and return the initial observation.
+
+        Args:
+            seed: Optional random seed for reproducibility.
+
+        Returns:
+            dict with keys: type, obs (47 floats), reward, done, info
+        """
+        self._ws.send(json.dumps({"type": "reset", "seed": seed}))
+        msg = json.loads(self._ws.recv())
+        if msg["type"] == "error":
+            raise RuntimeError(f"Simulator error: {msg['message']}")
+        return msg
+
+    def step(self, action: int) -> dict:
+        """Take one step in the environment.
+
+        Args:
+            action: Integer action in range 0-13.
+
+        Returns:
+            dict with keys: type, obs (47 floats), reward, done, info
+        """
+        self._ws.send(json.dumps({"type": "step", "action": action}))
+        msg = json.loads(self._ws.recv())
+        if msg["type"] == "error":
+            raise RuntimeError(f"Simulator error: {msg['message']}")
+        return msg
+
+    def close(self):
+        """Close the session and the underlying WebSocket connection."""
+        try:
+            self._ws.send(json.dumps({"type": "close"}))
+            self._ws.recv()
+        finally:
+            self._ws.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+
+class SimulatorGymResource:
+    def __init__(self, client):
+        self._client = client
+
+    def _ws_base_url(self) -> str:
+        url = self._client.base_url
+        if url.startswith("https://"):
+            return "wss://" + url[len("https://"):]
+        if url.startswith("http://"):
+            return "ws://" + url[len("http://"):]
+        return url
+
+    def connect(self, symbol: str, cal_date: str, exchange: str) -> GymSession:
+        """Open a new simulator-gym session.
+
+        Args:
+            symbol:    Trading symbol, e.g. "700.HK"
+            cal_date:  Calibration date, e.g. "2025-09-02"
+            exchange:  Exchange identifier, e.g. "HKEX.Securities"
+
+        Returns:
+            GymSession — use as a context manager:
+
+                with client.simulator_gym.connect("700.HK", "2025-09-02", "HKEX.Securities") as env:
+                    obs = env.reset(seed=42)
+                    result = env.step(0)
+        """
+        ws_url = f"{self._ws_base_url()}/ws/simulator-gym"
+        try:
+            ws = websocket.create_connection(
+                ws_url,
+                header={"X-API-Key": self._client.api_key},
+            )
+        except websocket.WebSocketBadStatusException as e:
+            if "403" in str(e):
+                raise RuntimeError(
+                    "Authentication failed: invalid or expired API key. "
+                    "Check your API key with client.api_keys.list()."
+                ) from e
+            raise RuntimeError(f"Failed to connect to simulator-gym: {e}") from e
+        except Exception as e:
+            raise RuntimeError(f"Failed to connect to simulator-gym: {e}") from e
+
+        ws.send(json.dumps({
+            "type": "create",
+            "config": {
+                "symbol": symbol,
+                "cal_date": cal_date,
+                "exchange": exchange,
+            }
+        }))
+
+        msg = json.loads(ws.recv())
+        if msg["type"] == "error":
+            ws.close()
+            raise RuntimeError(f"Failed to create session: {msg['message']}")
+        if msg["type"] != "created":
+            ws.close()
+            raise RuntimeError(f"Unexpected response type '{msg['type']}' during session creation")
+
+        return GymSession(ws, session_id=msg["session_id"])

simudyne/resources/validation.py

@@ -0,0 +1,234 @@
+"""
+Validation Resource for the Pulse SDK.
+
+This module provides methods for validating simulation quality by comparing
+simulated LOB data against historical data using distributional metrics,
+impact response analysis, and FID scores.
+
+Workflow:
+    1. Submit a validation job with run() -> returns job_id
+    2. Poll status with get_job(job_id) or use run_pipeline() for blocking
+    3. View results including distances and plots
+    4. List past jobs with list_jobs()
+"""
+
+import time
+import base64
+
+
+RUN_PATH = "/validation/run"
+JOBS_PATH = "/validation/jobs"
+
+
+class ValidationResource:
+    def __init__(self, client):
+        self._client = client
+
+    def run(
+        self,
+        symbol: str,
+        date: str,
+        sim_ids: list[str],
+        ticksize: float = 1.0,
+        run_metrics: bool = True,
+        run_impact: bool = False,
+        run_fid: bool = False,
+        n_levels: int = 10,
+        rescale_volumes: bool = True,
+        lot_size: int = 1,
+    ) -> dict:
+        """Submit a validation job.
+
+        Compares simulation output against historical market data using
+        distributional distance metrics (L1, Wasserstein), impact response
+        curves, and FID scores.
+
+        Historical data is fetched automatically from GCS based on symbol and date.
+        Simulation data is fetched from each sim_id's sim_data.parquet in GCS.
+
+        Args:
+            symbol: Trading symbol (e.g. "700.HK")
+            date: Calibration date in YYYY-MM-DD format (e.g. "2025-09-01")
+            sim_ids: List of simulation IDs to validate (max 25)
+            ticksize: Tick size for the symbol
+            run_metrics: Compute L1/Wasserstein distributional distances
+            run_impact: Compute impact response curves
+            run_fid: Compute Frechet Inception Distance
+            n_levels: Number of L2 book levels to use
+            rescale_volumes: Multiply simulated L2 size columns by lot_size
+            lot_size: Lot size multiplier for volume rescaling
+
+        Returns:
+            dict with job_id, status, message
+        """
+        payload = {
+            "symbol": symbol,
+            "date": date,
+            "sim_ids": sim_ids,
+            "ticksize": ticksize,
+            "config": {
+                "run_metrics": run_metrics,
+                "run_impact": run_impact,
+                "run_fid": run_fid,
+                "n_levels": n_levels,
+                "rescale_volumes": rescale_volumes,
+                "lot_size": lot_size,
+            },
+        }
+        return self._client._request("POST", RUN_PATH, json=payload)
+
+    def get_job(self, job_id: str) -> dict:
+        """Get validation job status and results.
+
+        Args:
+            job_id: The job ID returned by run()
+
+        Returns:
+            dict with:
+            - status: "pending", "running", "completed", or "failed"
+            - distances: dict of {metric: {l1: [...], w: [...]}} (when completed)
+            - fid_scores: list of floats (when completed and run_fid=True)
+            - plots: list of {name, content_base64} (when completed)
+            - metadata: dict with run parameters
+            - error: error message (when failed)
+        """
+        return self._client._request("GET", f"{JOBS_PATH}/{job_id}")
+
+    def list_jobs(self, limit: int = 50) -> dict:
+        """List validation jobs for the current user.
+
+        Args:
+            limit: Max number of jobs to return (default 50, max 200)
+
+        Returns:
+            dict with jobs list and total count
+        """
+        return self._client._request("GET", JOBS_PATH, params={"limit": limit})
+
+    def run_pipeline(
+        self,
+        symbol: str,
+        date: str,
+        sim_ids: list[str],
+        ticksize: float = 1.0,
+        run_metrics: bool = True,
+        run_impact: bool = False,
+        run_fid: bool = False,
+        n_levels: int = 10,
+        rescale_volumes: bool = True,
+        lot_size: int = 1,
+        poll_interval: float = 3.0,
+        timeout: float = 600.0,
+    ) -> dict:
+        """Submit a validation job and block until it completes.
+
+        Combines run() + polling get_job() into a single call.
+        Prints progress to stderr.
+
+        Args:
+            symbol: Trading symbol (e.g. "700.HK")
+            date: Calibration date in YYYY-MM-DD format
+            sim_ids: List of simulation IDs to validate (max 25)
+            ticksize: Tick size for the symbol
+            run_metrics: Compute L1/Wasserstein distributional distances
+            run_impact: Compute impact response curves
+            run_fid: Compute Frechet Inception Distance
+            n_levels: Number of L2 book levels to use
+            rescale_volumes: Multiply simulated L2 size columns by lot_size
+            lot_size: Lot size multiplier for volume rescaling
+            poll_interval: Seconds between status checks (default 3)
+            timeout: Max seconds to wait (default 600)
+
+        Returns:
+            dict with full validation results (distances, plots, metadata)
+
+        Raises:
+            RuntimeError: If the validation job fails
+            TimeoutError: If the job doesn't complete within timeout
+        """
+        import sys
+
+        job = self.run(
+            symbol=symbol,
+            date=date,
+            sim_ids=sim_ids,
+            ticksize=ticksize,
+            run_metrics=run_metrics,
+            run_impact=run_impact,
+            run_fid=run_fid,
+            n_levels=n_levels,
+            rescale_volumes=rescale_volumes,
+            lot_size=lot_size,
+        )
+        job_id = job["job_id"]
+        print(f"Validation job submitted: {job_id}", file=sys.stderr)
+
+        start = time.time()
+        while True:
+            result = self.get_job(job_id)
+            status = result["status"]
+
+            if status == "completed":
+                elapsed = time.time() - start
+                print(f"Completed in {elapsed:.1f}s", file=sys.stderr)
+                return result
+            elif status == "failed":
+                raise RuntimeError(f"Validation failed: {result.get('error')}")
+
+            if time.time() - start > timeout:
+                raise TimeoutError(f"Validation job {job_id} timed out after {timeout}s")
+
+            time.sleep(poll_interval)
+
+    def display_plots(self, result: dict) -> "PlotDisplay":
+        """Return a PlotDisplay object for displaying validation plots.
+
+        Usage:
+            plots = client.validation.display_plots(result)
+            plots.distributions()    # show distribution histograms
+            plots.distances()        # show spider plots
+            plots.impact_response()  # show impact response plots
+
+        Args:
+            result: The result dict from run_pipeline() or get_job()
+        """
+        return PlotDisplay(result)
+
+
+class PlotDisplay:
+    """Displays categorized validation plots inline in Jupyter notebooks."""
+
+    def __init__(self, result: dict):
+        plots = result.get("plots") or {}
+        self._distributions = plots.get("distributions", [])
+        self._distances = plots.get("distances", [])
+        self._impact_response = plots.get("impact_response", [])
+
+    def _show(self, plot_list, title):
+        from IPython.display import display, Image
+
+        if not plot_list:
+            print(f"No {title} plots available")
+            return
+
+        for plot in plot_list:
+            print(f"\n--- {plot['name']} ---")
+            display(Image(data=base64.b64decode(plot["content_base64"])))
+
+    def distributions(self):
+        """Display distribution histogram plots."""
+        self._show(self._distributions, "distribution")
+
+    def distances(self):
+        """Display spider plots (L1 and Wasserstein distances)."""
+        self._show(self._distances, "distance")
+
+    def impact_response(self):
+        """Display impact response plots."""
+        self._show(self._impact_response, "impact response")
+
+    def all(self):
+        """Display all plots."""
+        self.distances()
+        self.distributions()
+        self.impact_response()

simudyne_pulse-0.6.0.dev1.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: simudyne-pulse
+Version: 0.6.0.dev1
+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 `main` 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.dev1.dist-info/RECORD

@@ -0,0 +1,16 @@
+simudyne/__init__.py,sha256=m4FqChvvnm2ESEG1imAqGj7u-ksFxY6gPgRlyHFlL1c,92
+simudyne/client.py,sha256=7EHrhp1sdJVPn1EEmuqQnN-i82__gZ9CZ64cs5Cp_3U,4606
+simudyne/exceptions.py,sha256=ZfMiN4TTIMvqQ4EVfJ_4aNe3OvtZlzpWSyvfkuE5neo,270
+simudyne/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simudyne/resources/api_keys.py,sha256=Pu2srG6ymsf0Ax1VbeA3X0Ofs0pq8j6b42iQ81T0iUE,393
+simudyne/resources/data.py,sha256=_KH40tvLuMESJuH4t7ign7FKr2WcuObLRAF2bPpZbgg,241
+simudyne/resources/historical.py,sha256=-PkcCd7KRZyO2uG3GMpWgZjwmnmZL42-_4I_mJSbrww,76
+simudyne/resources/profile.py,sha256=XYMdRoF1s2NXvHdIBay0M3gkeuKf7P7YSK1XffoE1JM,1028
+simudyne/resources/simulation.py,sha256=xRc9PBmrh4OE5qh8pzs9WebOw2Utfx8uaMYOJ-IeNIg,28000
+simudyne/resources/simulator_gym.py,sha256=MWo7xv5fVFYpTAKU3sJVyHoDZvA8P0dDgSxgCindCMk,3873
+simudyne/resources/validation.py,sha256=V8-IFEKa8s0mlqHzT1kQ1j_OKKLFcM9RGx53p7a65uQ,8025
+simudyne_pulse-0.6.0.dev1.dist-info/licenses/LICENSE,sha256=H_hgosvz8TIG6NAgsaluNzCBOe3lHZddEWwyJM9PTWs,1069
+simudyne_pulse-0.6.0.dev1.dist-info/METADATA,sha256=fCIMn2TD-pvUseI2f3kII3qBnJLRxtppUiGRSFTt344,4141
+simudyne_pulse-0.6.0.dev1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+simudyne_pulse-0.6.0.dev1.dist-info/top_level.txt,sha256=PT1iWu7CFbICTaYJ7vZSKdup-YPFtHV5j2y5LPe6UP0,9
+simudyne_pulse-0.6.0.dev1.dist-info/RECORD,,

simudyne_pulse-0.6.0.dev1.dist-info/WHEEL

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

simudyne_pulse-0.6.0.dev1.dist-info/licenses/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.dev1.dist-info/top_level.txt

@@ -0,0 +1 @@
+simudyne