simudyne-pulse 0.7.0__tar.gz → 0.7.0.dev1__tar.gz

{simudyne_pulse-0.7.0/src/simudyne_pulse.egg-info → simudyne_pulse-0.7.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simudyne-pulse
-Version: 0.7.0
+Version: 0.7.0.dev1
 Summary: Python SDK for the Simudyne Pulse synthetic market data API
 Author-email: Simudyne <support@simudyne.com>
 License-Expression: MIT

{simudyne_pulse-0.7.0 → simudyne_pulse-0.7.0.dev1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simudyne-pulse"
-version = "0.7.0"
+version = "0.7.0-dev.1"
 description = "Python SDK for the Simudyne Pulse synthetic market data API"
 readme = "README.md"
 license = "MIT"

simudyne_pulse-0.7.0.dev1/src/simudyne/resources/validation.py

@@ -0,0 +1,411 @@
+"""
+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, stylised facts, and the MIND/FID inception distances
+on DeepLOB embeddings.
+
+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()
+
+For the inception distances alone, inception_distances() is a one-call
+shortcut that returns just the MIND and FID scores.
+
+Tri-state run flags
+-------------------
+``run_metrics`` / ``run_impact`` / ``run_stylised_facts`` / ``plot_data``
+default to ``None``, meaning "use the default for my tier" — resolved
+server-side. Demo turns everything on; other tiers get metrics and stylised
+facts. Only flags you set explicitly are sent, so a demo key is not silently
+opted out of the passes it is entitled to. Pass ``False`` to skip an expensive
+pass, or ``True`` to force one on.
+
+``run_inception_distances`` is the exception: it defaults to ``True``, so MIND
+and FID are computed unless you opt out. It maps to the API's ``run_fid``
+config field, which gates both metrics because they share one DeepLOB
+embedding pass. Note the scores are returned to the demo tier only — on any
+other tier a ``True`` here spends the embedding pass and the response withholds
+the numbers, so pass ``False`` if that is your situation.
+"""
+
+import base64
+import time
+
+
+RUN_PATH = "/validation/run"
+JOBS_PATH = "/validation/jobs"
+
+#: Flags the API resolves from the caller's tier when left unset.
+_TRI_STATE_FLAGS = (
+    "run_metrics",
+    "run_impact",
+    "run_stylised_facts",
+    "plot_data",
+)
+
+#: SDK name -> API config field. The API kept ``run_fid`` for compatibility;
+#: the SDK spells out what it actually gates.
+_INCEPTION_WIRE_FIELD = "run_fid"
+
+
+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 = None,
+        run_impact: bool = None,
+        run_inception_distances: bool = True,
+        run_stylised_facts: bool = None,
+        plot_data: bool = None,
+        n_levels: int = 10,
+        l2_only: bool = False,
+        provider: str = None,
+        exchange: str = None,
+    ) -> dict:
+        """Submit a validation job.
+
+        Compares simulation output against historical market data using
+        distributional distance metrics (L1, Wasserstein), impact response
+        curves, Cont stylised facts, and the MIND/FID inception distances.
+
+        Historical data is fetched automatically based on symbol and date.
+        Simulation data is fetched from each sim_id's sim_data.parquet.
+
+        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
+                (None = tier default)
+            run_impact: Compute impact response curves (None = tier default).
+                Only computed when plot_data is on — it has no verdict-only form.
+            run_inception_distances: Compute MIND *and* FID on DeepLOB
+                embeddings (default True). One flag gates both — they share a
+                single embedding pass. Sent as the API's ``run_fid`` field.
+                The scores reach the demo tier only, so on another tier this
+                spends the pass and the response withholds the numbers.
+            run_stylised_facts: Compute the 11 Cont stylised facts
+                (None = tier default)
+            plot_data: Store the raw data behind every plot — distribution
+                histograms, full stylised-fact payloads, impact curves.
+                **Demo tier only**; an explicit True from any other tier is
+                rejected with 403. When off, the job returns distances and the
+                per-fact verdicts only.
+            n_levels: Number of L2 book levels to use. The inception distances
+                need all 10.
+            l2_only: Restrict to metrics that need only bid/ask price+size.
+                Disables the impact response.
+            provider: Data provider (e.g. "omd"). Defaults to the prefix parsed
+                from sim_ids[0].
+            exchange: Exchange protocol (e.g. "hkex_securities"). Defaults to
+                the prefix parsed from sim_ids[0].
+
+        Returns:
+            dict with job_id, status, message
+        """
+        config = {
+            "n_levels": n_levels,
+            "l2_only": l2_only,
+            _INCEPTION_WIRE_FIELD: run_inception_distances,
+        }
+        for flag, value in zip(
+            _TRI_STATE_FLAGS,
+            (run_metrics, run_impact, run_stylised_facts, plot_data),
+        ):
+            # Omitted rather than sent as None: the API reads absence as "use my
+            # tier's default", and sending an explicit null would not do that.
+            if value is not None:
+                config[flag] = value
+
+        payload = {
+            "symbol": symbol,
+            "date": date,
+            "sim_ids": sim_ids,
+            "ticksize": ticksize,
+            "config": config,
+        }
+        if provider is not None:
+            payload["provider"] = provider
+        if exchange is not None:
+            payload["exchange"] = exchange
+
+        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: {metric: {l1: [...], w: [...]}} — every entitled tier
+            - stylised_fact_verdicts: {fact: {historical: bool | None,
+              simulated: [bool | None, ...]}} — every entitled tier
+            - mind_scores: one Monge Inception Distance per sim run, in sim_ids
+              order; None where a run could not be embedded. Demo tier only
+            - fid_scores: one Frechet Inception Distance per sim run, same
+              ordering and tier rule. Since pulse-check 1.8.0 this is the
+              embedding-space FID — not comparable with values stored by older
+              jobs
+            - distributions / impact_response / stylised_facts: the full
+              historical-derived payloads. Demo tier, plot_data jobs only
+            - plots: {distributions: [...], distances: [...],
+              impact_response: [...]} of {name, content_base64}
+            - metadata: dict with run parameters
+            - error: error message (when failed)
+
+        Lower MIND/FID = closer to the historical day. Neither is meaningful as
+        a bare number — see inception_distances() for how to read them.
+        """
+        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 = None,
+        run_impact: bool = None,
+        run_inception_distances: bool = True,
+        run_stylised_facts: bool = None,
+        plot_data: bool = None,
+        n_levels: int = 10,
+        l2_only: bool = False,
+        provider: str = None,
+        exchange: str = None,
+        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 distances (None = tier default)
+            run_impact: Compute impact response curves (None = tier default)
+            run_inception_distances: Compute MIND *and* FID on DeepLOB
+                embeddings (default True) — one flag gates both
+            run_stylised_facts: Compute the Cont stylised facts
+                (None = tier default)
+            plot_data: Store the raw plottable data (demo tier only)
+            n_levels: Number of L2 book levels to use
+            l2_only: Restrict to L2-only metrics
+            provider: Data provider; defaults to the sim_id prefix
+            exchange: Exchange protocol; defaults to the sim_id prefix
+            poll_interval: Seconds between status checks (default 3)
+            timeout: Max seconds to wait (default 600)
+
+        Returns:
+            dict with full validation results — see get_job() for the fields
+
+        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_inception_distances=run_inception_distances,
+            run_stylised_facts=run_stylised_facts,
+            plot_data=plot_data,
+            n_levels=n_levels,
+            l2_only=l2_only,
+            provider=provider,
+            exchange=exchange,
+        )
+        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 inception_distances(
+        self,
+        symbol: str,
+        date: str,
+        sim_ids: list[str],
+        ticksize: float = 1.0,
+        n_levels: int = 10,
+        provider: str = None,
+        exchange: str = None,
+        poll_interval: float = 3.0,
+        timeout: float = 600.0,
+    ) -> dict:
+        """MIND and FID for each simulation, and nothing else.
+
+        A focused shortcut over run_pipeline(): keeps the inception distances
+        on and forces every other pass off, so the job does one DeepLOB embedding pass
+        and skips the metric, impact and stylised-fact work.
+
+        Both metrics are computed on 96-dim DeepLOB embeddings of 100-row L2
+        windows and need 10 book levels in the data.
+
+        Args:
+            symbol: Trading symbol (e.g. "700.HK")
+            date: Calibration date in YYYY-MM-DD format
+            sim_ids: List of simulation IDs to score (max 25)
+            ticksize: Tick size for the symbol
+            n_levels: Number of L2 book levels (10 required for the embeddings)
+            provider: Data provider; defaults to the sim_id prefix
+            exchange: Exchange protocol; defaults to the sim_id prefix
+            poll_interval: Seconds between status checks
+            timeout: Max seconds to wait
+
+        Returns:
+            dict with:
+            - mind: list of MIND scores, one per sim_id, None where a run could
+              not be embedded
+            - fid: list of FID scores, same ordering and convention
+            - sim_ids: the ids, so scores can be zipped back to their runs
+            - job_id: the underlying validation job
+
+        Raises:
+            RuntimeError: If the job fails, or if the scores come back empty —
+                which means the pipeline skipped them (missing torch, fewer
+                than 10 levels, unreachable checkpoint) or the key is not on
+                the demo tier, both of which are silent in the raw response.
+
+        Interpreting the scores:
+            Lower = closer to the historical day, but neither number means
+            anything on its own — only relative to a noise floor. Score a
+            real-vs-real control too (two slices of genuine market data) and
+            read a generator as a multiple of that floor. ~1x means the metric
+            cannot separate it from ordinary intraday variation.
+        """
+        result = self.run_pipeline(
+            symbol=symbol,
+            date=date,
+            sim_ids=sim_ids,
+            ticksize=ticksize,
+            run_inception_distances=True,
+            run_metrics=False,
+            run_impact=False,
+            run_stylised_facts=False,
+            n_levels=n_levels,
+            provider=provider,
+            exchange=exchange,
+            poll_interval=poll_interval,
+            timeout=timeout,
+        )
+
+        mind = result.get("mind_scores")
+        fid = result.get("fid_scores")
+        if not mind and not fid:
+            raise RuntimeError(
+                "no inception distances in the response. Either the pipeline "
+                "skipped them (torch missing, fewer than 10 book levels, or "
+                "the DeepLOB checkpoint unreachable) or this API key is not on "
+                "the demo tier, which is the only tier they are shared with."
+            )
+
+        return {
+            "mind": mind,
+            "fid": fid,
+            "sim_ids": list(sim_ids),
+            "job_id": result.get("job_id"),
+        }
+
+    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.7.0 → simudyne_pulse-0.7.0.dev1/src/simudyne_pulse.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simudyne-pulse
-Version: 0.7.0
+Version: 0.7.0.dev1
 Summary: Python SDK for the Simudyne Pulse synthetic market data API
 Author-email: Simudyne <support@simudyne.com>
 License-Expression: MIT

{simudyne_pulse-0.7.0 → simudyne_pulse-0.7.0.dev1}/src/simudyne_pulse.egg-info/SOURCES.txt

@@ -17,4 +17,5 @@ src/simudyne_pulse.egg-info/SOURCES.txt
 src/simudyne_pulse.egg-info/dependency_links.txt
 src/simudyne_pulse.egg-info/requires.txt
 src/simudyne_pulse.egg-info/top_level.txt
-tests/test_simulator_gym.py
+tests/test_simulator_gym.py
+tests/test_validation.py

simudyne_pulse-0.7.0.dev1/tests/test_validation.py

@@ -0,0 +1,158 @@
+"""Tests for the validation resource's request payloads and score handling.
+
+No network: the client's _request is replaced with a recorder, so these assert
+the exact payload the API receives — which is what actually broke when
+pulse-check 1.8.0 dropped rescale_volumes/lot_size and made run_fid gate both
+inception distances.
+"""
+
+import pytest
+
+from simudyne.resources.validation import ValidationResource
+
+
+class FakeClient:
+    """Records calls and replays queued responses."""
+
+    def __init__(self, responses=None):
+        self.calls = []
+        self._responses = list(responses or [])
+
+    def _request(self, method, path, **kwargs):
+        self.calls.append((method, path, kwargs))
+        return self._responses.pop(0) if self._responses else {}
+
+
+SIM_IDS = ["omd:hkex_securities:700.HK:2025-12-22:abc:normal:baseline:0000"]
+
+
+class TestRunPayload:
+    def test_unset_flags_are_omitted_so_the_tier_default_applies(self):
+        client = FakeClient([{"job_id": "v1", "status": "pending"}])
+        ValidationResource(client).run("700.HK", "2025-12-22", SIM_IDS)
+
+        _, path, kwargs = client.calls[0]
+        config = kwargs["json"]["config"]
+        assert path == "/validation/run"
+        # Sending these as null would override the server-side tier default.
+        for flag in ("run_metrics", "run_impact",
+                     "run_stylised_facts", "plot_data"):
+            assert flag not in config, f"{flag} must be omitted when unset"
+        # run_inception_distances is NOT tri-state: it defaults to True and is
+        # always sent, as the API's run_fid field.
+        assert config == {"n_levels": 10, "l2_only": False, "run_fid": True}
+
+    def test_explicit_flags_are_sent(self):
+        client = FakeClient([{"job_id": "v1"}])
+        ValidationResource(client).run(
+            "700.HK", "2025-12-22", SIM_IDS, run_impact=False
+        )
+
+        config = client.calls[0][2]["json"]["config"]
+        # An explicit False must survive — it is how a demo user skips a pass.
+        assert config["run_impact"] is False
+
+    def test_inception_distances_can_be_opted_out(self):
+        """Non-demo tiers should be able to skip the embedding pass."""
+        client = FakeClient([{"job_id": "v1"}])
+        ValidationResource(client).run(
+            "700.HK", "2025-12-22", SIM_IDS, run_inception_distances=False
+        )
+        assert client.calls[0][2]["json"]["config"]["run_fid"] is False
+
+    def test_old_run_fid_kwarg_is_rejected(self):
+        """Renamed to run_inception_distances — the old spelling must fail loudly."""
+        with pytest.raises(TypeError):
+            ValidationResource(FakeClient([{}])).run(
+                "700.HK", "2025-12-22", SIM_IDS, run_fid=True
+            )
+
+    def test_removed_params_are_not_accepted(self):
+        """rescale_volumes/lot_size went away with pulse-check 1.8.0."""
+        resource = ValidationResource(FakeClient([{}]))
+        with pytest.raises(TypeError):
+            resource.run("700.HK", "2025-12-22", SIM_IDS, rescale_volumes=True)
+        with pytest.raises(TypeError):
+            resource.run("700.HK", "2025-12-22", SIM_IDS, lot_size=100)
+
+    def test_provider_and_exchange_omitted_unless_given(self):
+        client = FakeClient([{}, {}])
+        r = ValidationResource(client)
+        r.run("700.HK", "2025-12-22", SIM_IDS)
+        assert "provider" not in client.calls[0][2]["json"]
+
+        r.run("700.HK", "2025-12-22", SIM_IDS, provider="omd", exchange="lse")
+        payload = client.calls[1][2]["json"]
+        assert payload["provider"] == "omd" and payload["exchange"] == "lse"
+
+
+class TestInceptionDistances:
+    def _completed(self, **extra):
+        return {"job_id": "v1", "status": "completed", **extra}
+
+    def test_forces_fid_on_and_everything_else_off(self):
+        client = FakeClient([
+            {"job_id": "v1", "status": "pending"},
+            self._completed(mind_scores=[12.5], fid_scores=[8.25]),
+        ])
+        out = ValidationResource(client).inception_distances(
+            "700.HK", "2025-12-22", SIM_IDS, poll_interval=0
+        )
+
+        config = client.calls[0][2]["json"]["config"]
+        assert config["run_fid"] is True  # wire name for run_inception_distances
+        assert config["run_metrics"] is False
+        assert config["run_impact"] is False
+        assert config["run_stylised_facts"] is False
+
+        assert out["mind"] == [12.5]
+        assert out["fid"] == [8.25]
+        assert out["sim_ids"] == SIM_IDS
+        assert out["job_id"] == "v1"
+
+    def test_none_scores_are_preserved_to_keep_indexing_aligned(self):
+        two = SIM_IDS * 2
+        client = FakeClient([
+            {"job_id": "v1", "status": "pending"},
+            self._completed(mind_scores=[12.5, None], fid_scores=[8.25, None]),
+        ])
+        out = ValidationResource(client).inception_distances(
+            "700.HK", "2025-12-22", two, poll_interval=0
+        )
+        assert out["mind"] == [12.5, None]
+        assert len(out["mind"]) == len(out["sim_ids"])
+
+    def test_missing_scores_raise_rather_than_returning_empty(self):
+        """A skipped pass or a non-demo key is silent in the raw response."""
+        client = FakeClient([
+            {"job_id": "v1", "status": "pending"},
+            self._completed(mind_scores=None, fid_scores=None),
+        ])
+        with pytest.raises(RuntimeError, match="no inception distances"):
+            ValidationResource(client).inception_distances(
+                "700.HK", "2025-12-22", SIM_IDS, poll_interval=0
+            )
+
+
+class TestRunPipeline:
+    def test_raises_on_failed_job(self):
+        client = FakeClient([
+            {"job_id": "v1", "status": "pending"},
+            {"job_id": "v1", "status": "failed", "error": "boom"},
+        ])
+        with pytest.raises(RuntimeError, match="boom"):
+            ValidationResource(client).run_pipeline(
+                "700.HK", "2025-12-22", SIM_IDS, poll_interval=0
+            )
+
+    def test_returns_the_completed_result(self):
+        client = FakeClient([
+            {"job_id": "v1", "status": "pending"},
+            {"job_id": "v1", "status": "running"},
+            {"job_id": "v1", "status": "completed", "distances": {"spread": {}}},
+        ])
+        result = ValidationResource(client).run_pipeline(
+            "700.HK", "2025-12-22", SIM_IDS, poll_interval=0
+        )
+        assert result["status"] == "completed"
+        assert "spread" in result["distances"]

simudyne_pulse-0.7.0/src/simudyne/resources/validation.py

@@ -1,267 +0,0 @@
-"""
-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 | None = None,
-        run_impact: bool | None = None,
-        run_fid: bool | None = None,
-        run_stylised_facts: bool | None = None,
-        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.
-                Leave unset to use your tier's default.
-            run_impact: Compute impact response curves. Leave unset to use your
-                tier's default.
-            run_fid: Compute Frechet Inception Distance. Leave unset to use your
-                tier's default.
-            run_stylised_facts: Compute stylised facts (autocorrelation, heavy
-                tails, volatility clustering). Leave unset to use your tier's
-                default.
-            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
-        """
-        # A run_* flag left unset is omitted so the API applies your tier's
-        # default rather than an SDK-side one. Sending False for the optional
-        # passes would silently opt demo accounts out of the extra results that
-        # tier is meant to return by default.
-        config = {
-            "n_levels": n_levels,
-            "rescale_volumes": rescale_volumes,
-            "lot_size": lot_size,
-        }
-        for flag, value in (
-            ("run_metrics", run_metrics),
-            ("run_impact", run_impact),
-            ("run_fid", run_fid),
-            ("run_stylised_facts", run_stylised_facts),
-        ):
-            if value is not None:
-                config[flag] = value
-
-        payload = {
-            "symbol": symbol,
-            "date": date,
-            "sim_ids": sim_ids,
-            "ticksize": ticksize,
-            "config": config,
-        }
-        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)
-            - metadata: dict with run parameters, including which passes ran
-            - error: error message (when failed)
-
-            Demo-tier accounts additionally receive the numbers derived from the
-            historical data, which are withheld at the pro tier:
-
-            - distributions: per-metric historical vs simulated histograms
-            - impact_response: impact response curves as numbers, historical and
-              one block per sim run
-            - stylised_facts: historical and one block per sim run
-            - fid_scores: one score per sim run (None where not computable)
-        """
-        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 | None = None,
-        run_impact: bool | None = None,
-        run_fid: bool | None = None,
-        run_stylised_facts: bool | None = None,
-        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.
-                Leave unset to use your tier's default.
-            run_impact: Compute impact response curves. Leave unset to use your
-                tier's default.
-            run_fid: Compute Frechet Inception Distance. Leave unset to use your
-                tier's default.
-            run_stylised_facts: Compute stylised facts (autocorrelation, heavy
-                tails, volatility clustering). Leave unset to use your tier's
-                default.
-            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,
-            run_stylised_facts=run_stylised_facts,
-            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()