simudyne-pulse 0.7.0.dev6__tar.gz → 0.7.0.dev7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simudyne-pulse
-Version: 0.7.0.dev6
+Version: 0.7.0.dev7
 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.dev6 → simudyne_pulse-0.7.0.dev7}/pyproject.toml

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

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

@@ -0,0 +1,346 @@
+"""
+Validation Resource for the Pulse SDK.
+
+Compares simulated LOB data against a historical day using distributional
+metrics, impact response, Cont's stylised facts, cross-level volume
+correlation, and the MIND/FID inception distances on DeepLOB embeddings.
+
+Submit, then poll::
+
+    job = client.validation.run(
+        symbol="BARC", date="2026-06-17", provider="bmll", exchange="lse",
+        sim_ids=[...], ticksize=0.05,
+    )
+    result = client.validation.get_job(job["job_id"])
+    result["distances"]["spread"]["l1"]        # per simulation
+    result["stylised_fact_verdicts"]["heavy_tails"]
+
+``run`` submits and returns; a validation of a real day takes minutes, so
+``get_job`` is the status endpoint you call until it is done. ``list_jobs``
+reaches past runs.
+
+Selecting metrics
+-----------------
+One flag per metric — ``statistical``, ``stylised_facts``, ``impact``,
+``volume_correlation``, ``fid``, ``mind``. Left as ``None`` each takes the
+default for your tier, resolved server-side, so naming none behaves exactly as
+your account is entitled to. Pass ``False`` to skip an expensive pass or
+``True`` to force one on.
+
+The historical gate
+-------------------
+Whether the historical half of the comparison comes back — the series in the
+JSON *and* the historical trace on any rendered plot — is decided by your tier,
+not by a parameter here. What is never gated: the L1 and Wasserstein
+``distances``, the FID and MIND scores, and the true/false
+``stylised_fact_verdicts`` for both the historical day and each simulation.
+Those are derived scalars and booleans, not series, so every tier receives
+them.
+"""
+
+import json
+from pathlib import Path
+
+
+RUN_PATH = "/validation/run"
+UPLOAD_PATH = "/validation/run/upload"
+JOBS_PATH = "/validation/jobs"
+
+#: The API rejects more per job; checked client-side so a 26-file submission
+#: fails before any bytes are uploaded.
+MAX_SIM_FILES = 25
+
+#: One flag per area of checking. Left unset each takes the server's default.
+_AREA_FLAGS = (
+    "statistical",
+    "stylised_facts",
+    "impact",
+    "volume_correlation",
+    "fid",
+    "mind",
+)
+
+#: ``lob`` marks the frames as L2 snapshots, which switches off anything
+#: needing the message stream; ``sample_period`` and ``match_generated_sample``
+#: set the grid the book is resampled onto; ``plots`` is False, True, or a list
+#: of plot ids.
+_EXTRA_FIELDS = ("lob", "sample_period", "match_generated_sample", "plots")
+
+
+def _frame_to_parquet(entry, index: int):
+    """Normalise one simulated run to ``(filename, parquet bytes)``.
+
+    Accepts a path, a ``(filename, bytes)`` pair, or a polars / pandas
+    DataFrame, which is written to parquet in memory. The frame must be pulse
+    format -- the same shape the engine writes to ``sim_data.parquet`` -- which
+    the server validates; sending something else fails there, not here.
+    """
+    import io
+
+    if isinstance(entry, tuple):
+        return entry
+
+    # Duck-typed rather than imported: neither polars nor pandas is a hard
+    # dependency of the SDK, and importing one to test for the other would
+    # make it one.
+    writer = getattr(entry, "write_parquet", None)      # polars
+    if writer is not None:
+        buf = io.BytesIO()
+        writer(buf)
+        return f"sim_{index}.parquet", buf.getvalue()
+
+    writer = getattr(entry, "to_parquet", None)          # pandas
+    if writer is not None:
+        buf = io.BytesIO()
+        writer(buf, index=False)
+        return f"sim_{index}.parquet", buf.getvalue()
+
+    path = Path(entry)
+    return path.name, path.read_bytes()
+
+
+def _build_config(n_levels, **flags) -> dict:
+    """The validation config as the API expects it.
+
+    Flags left as ``None`` are omitted rather than sent as null: the API reads
+    absence as "use my tier's default", and an explicit null would not do that.
+    """
+    config = {"n_levels": n_levels}
+    for name in _AREA_FLAGS + _EXTRA_FIELDS:
+        value = flags.get(name)
+        if value is not None:
+            config[name] = value
+
+    unknown = set(flags) - set(_AREA_FLAGS) - set(_EXTRA_FIELDS)
+    if unknown:
+        raise ValueError(
+            f"Unknown validation option(s): {sorted(unknown)}. "
+            f"Valid: {sorted(_AREA_FLAGS + _EXTRA_FIELDS)}"
+        )
+    return config
+
+
+def _save_plots(result: dict, plot_dir=None) -> list:
+    """Write the returned figures to disk and return the paths written.
+
+    The API sends rendered plots base64-encoded in the response. Left to
+    itself that is bytes you cannot look at, so when plots were asked for they
+    are written out: to ``plot_dir`` when given, otherwise the current
+    directory. The directory is created if it does not exist.
+    """
+    import base64
+
+    target = Path(plot_dir) if plot_dir is not None else Path.cwd()
+    target.mkdir(parents=True, exist_ok=True)
+
+    written = []
+    for category, entries in (result.get("plots") or {}).items():
+        for entry in entries or []:
+            content = entry.get("content_base64")
+            if not content:
+                continue
+            path = target / f"{entry.get('name') or category}.png"
+            path.write_bytes(base64.b64decode(content))
+            written.append(str(path))
+    return written
+
+
+class ValidationResource:
+    """Validate simulated market data against a historical day."""
+
+    def __init__(self, client):
+        self._client = client
+
+    def run(
+        self,
+        symbol: str,
+        date: str,
+        provider: str,
+        exchange: str,
+        *,
+        sim_ids=None,
+        sim_files=None,
+        ticksize: float = 1.0,
+        statistical=None,
+        stylised_facts=None,
+        impact=None,
+        volume_correlation=None,
+        fid=None,
+        mind=None,
+        lob=None,
+        sample_period=None,
+        match_generated_sample=None,
+        n_levels: int = 10,
+        plots=None,
+    ) -> dict:
+        """Submit a validation job.
+
+        Returns as soon as the job is accepted. Poll :meth:`get_job` for
+        status and, once it is complete, the result — a validation of a real
+        day takes minutes, which is far too long to hold a request open.
+
+        Parameters
+        ----------
+        symbol : str
+            Trading symbol, e.g. ``"BARC"`` or ``"700.HK"``.
+        date : str
+            Calibration date, ``"YYYY-MM-DD"``. The historical day compared
+            against.
+        provider : str
+            Data provider, ``"bmll"`` or ``"omd"``. Required: the same symbol
+            exists under both with different dates and tick sizes, so
+            ``(symbol, provider, exchange)`` is the identity, not the symbol.
+        exchange : str
+            Exchange, e.g. ``"lse"`` or ``"hkex_securities"``.
+        sim_ids : list of str, optional
+            Platform simulation IDs, 1 to 25. Exactly one of ``sim_ids`` or
+            ``sim_files`` is required.
+        sim_files : list, optional
+            Your own simulated runs, up to 25: paths, ``(filename, bytes)``
+            pairs, or polars / pandas DataFrames in pulse format. The
+            historical side is fetched for you.
+        ticksize : float, default 1.0
+            Minimum price increment. Should match the instrument.
+        statistical, stylised_facts, impact, volume_correlation, fid, mind : bool, optional
+            Whether to run each area. ``None`` uses your tier's default.
+        lob : bool, optional
+            The frames are L2 snapshots. Anything needing the message stream
+            is skipped, with the reason reported in
+            ``metadata["areas_skipped"]``.
+        sample_period : str, optional
+            The grid the book is resampled onto in lob mode, e.g. ``"1s"``.
+            Omitted, the cadence is read off your generated frames; if those
+            are event-level there is no grid to match and nothing is
+            resampled.
+        match_generated_sample : bool, optional
+            Match the generated frames' grid even when ``sample_period`` is
+            given.
+        n_levels : int, default 10
+            Book levels to measure over.
+        plots : bool or list of str, optional
+            ``None`` or ``False`` for none, ``True`` for every figure, or plot
+            ids such as ``["statistical.radar", "stylised_facts.overall"]``.
+            Rendered server-side; :meth:`get_job` writes them to disk.
+
+        Returns
+        -------
+        dict
+            ``{"job_id": str, "status": str, "message": str}``. Pass the
+            job_id to :meth:`get_job`.
+
+        Raises
+        ------
+        ValueError
+            If the parameters are invalid.
+        """
+        if (sim_ids is None) == (sim_files is None):
+            raise ValueError("Pass exactly one of sim_ids or sim_files")
+        if sim_ids is not None and not sim_ids:
+            raise ValueError("sim_ids must not be empty")
+        if sim_files is not None and not sim_files:
+            raise ValueError("sim_files must not be empty")
+        count = len(sim_ids if sim_ids is not None else sim_files)
+        if count > MAX_SIM_FILES:
+            raise ValueError(f"Maximum {MAX_SIM_FILES} simulations per validation job")
+        if ticksize <= 0:
+            raise ValueError("ticksize must be positive")
+        if n_levels < 1:
+            raise ValueError("n_levels must be at least 1")
+
+        config = _build_config(
+            n_levels,
+            statistical=statistical,
+            stylised_facts=stylised_facts,
+            impact=impact,
+            volume_correlation=volume_correlation,
+            fid=fid,
+            mind=mind,
+            lob=lob,
+            sample_period=sample_period,
+            match_generated_sample=match_generated_sample,
+            plots=plots,
+        )
+
+        if sim_ids is not None:
+            submitted = self._client._request(
+                "POST",
+                RUN_PATH,
+                json={
+                    "symbol": symbol,
+                    "date": date,
+                    "provider": provider,
+                    "exchange": exchange,
+                    "sim_ids": list(sim_ids),
+                    "ticksize": ticksize,
+                    "config": config,
+                },
+            )
+        else:
+            files = [
+                ("sim_files", _frame_to_parquet(entry, i))
+                for i, entry in enumerate(sim_files)
+            ]
+            submitted = self._client._request(
+                "POST",
+                UPLOAD_PATH,
+                files=files,
+                data={
+                    "symbol": symbol,
+                    "date": date,
+                    "provider": provider,
+                    "exchange": exchange,
+                    "ticksize": str(ticksize),
+                    "config": json.dumps(config),
+                },
+            )
+
+        if not (submitted or {}).get("job_id"):
+            raise ValueError(f"Validation API returned no job_id: {submitted}")
+        return submitted
+
+
+    def get_job(self, job_id: str, plot_dir=None) -> dict:
+        """Fetch a validation job's status, and its result once it is done.
+
+        This is the status endpoint: call it until ``status`` is
+        ``"completed"`` or ``"failed"``.
+
+        Parameters
+        ----------
+        job_id : str
+            From :meth:`run`.
+        plot_dir : str or Path, optional
+            Where to write any figures the job rendered. Defaults to the
+            current directory; created if it does not exist. Only has an
+            effect once the job is complete and only if ``plots`` was set on
+            the run. The paths written come back in ``plot_paths``.
+
+        Returns
+        -------
+        dict
+            ``job_id``, ``status``, ``symbol``, ``date`` and, once complete:
+            ``metadata``, ``distances``, ``distributions``,
+            ``impact_response``, ``stylised_facts``,
+            ``stylised_fact_verdicts``, ``volume_correlation``,
+            ``fid_scores``, ``mind_scores`` — enough to rebuild every figure —
+            plus ``plot_paths`` when figures were written.
+        """
+        job = self._client._request("GET", f"{JOBS_PATH}/{job_id}")
+        if (job or {}).get("plots"):
+            job["plot_paths"] = _save_plots(job, plot_dir)
+        return job
+
+    def list_jobs(self, limit: int = 50) -> dict:
+        """List your validation jobs, newest first.
+
+        Parameters
+        ----------
+        limit : int, default 50
+            Maximum number of jobs to return.
+
+        Returns
+        -------
+        dict
+            ``{"jobs": list, "total": int}``.
+        """
+        return self._client._request("GET", JOBS_PATH, params={"limit": limit})

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simudyne-pulse
-Version: 0.7.0.dev6
+Version: 0.7.0.dev7
 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.dev7/tests/test_validation.py

@@ -0,0 +1,230 @@
+"""Tests for the validation resource.
+
+No network: the client's ``_request`` is replaced with a recorder, so these
+assert the exact payload the API receives and the exact result handed back.
+
+The surface is one call — ``run`` submits, waits and returns the finished
+result — so most of what is worth pinning is what it sends, what it refuses to
+send, and what it does with the response.
+"""
+
+import base64
+import json
+
+import pytest
+
+from simudyne.resources.validation import MAX_SIM_FILES, 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"]
+IDENTITY = dict(symbol="700.HK", date="2025-12-22", provider="omd",
+                exchange="hkex_securities")
+
+PNG = base64.b64encode(b"\x89PNG\r\n\x1a\nfake").decode()
+
+
+def _run(responses, **kwargs):
+    client = FakeClient(responses)
+    result = ValidationResource(client).run(
+        sim_ids=SIM_IDS, **{**IDENTITY, **kwargs}
+    )
+    return client, result
+
+
+def _done(**extra):
+    return {"job_id": "v1", "status": "completed", **extra}
+
+
+class TestIdentityIsRequired:
+    """The same symbol exists under two providers with different tick sizes,
+    so the symbol alone never identified an instrument."""
+
+    @pytest.mark.parametrize("missing", ["symbol", "date", "provider", "exchange"])
+    def test_every_identity_field_is_required(self, missing):
+        kwargs = {k: v for k, v in IDENTITY.items() if k != missing}
+        with pytest.raises(TypeError):
+            ValidationResource(FakeClient()).run(sim_ids=SIM_IDS, **kwargs)
+
+
+class TestWhatToValidate:
+    def test_sim_ids_go_as_json(self):
+        client, _ = _run([{"job_id": "v1"}])
+        method, path, kwargs = client.calls[0]
+        assert (method, path) == ("POST", "/validation/run")
+        assert kwargs["json"]["sim_ids"] == SIM_IDS
+        assert kwargs["json"]["provider"] == "omd"
+
+    def test_sim_files_go_as_multipart_to_the_upload_route(self):
+        client = FakeClient([{"job_id": "v1"}])
+        ValidationResource(client).run(
+            sim_files=[("a.parquet", b"x"), ("b.parquet", b"y")], **IDENTITY
+        )
+        method, path, kwargs = client.calls[0]
+        assert (method, path) == ("POST", "/validation/run/upload")
+        assert len(kwargs["files"]) == 2
+        assert json.loads(kwargs["data"]["config"])["n_levels"] == 10
+
+    @pytest.mark.parametrize(
+        "kwargs,match",
+        [
+            ({}, "exactly one"),
+            ({"sim_ids": SIM_IDS, "sim_files": [("a", b"x")]}, "exactly one"),
+            ({"sim_ids": []}, "must not be empty"),
+            ({"sim_ids": SIM_IDS * (MAX_SIM_FILES + 1)}, "Maximum 25"),
+            ({"sim_ids": SIM_IDS, "ticksize": 0}, "ticksize must be positive"),
+            ({"sim_ids": SIM_IDS, "n_levels": 0}, "at least 1"),
+        ],
+    )
+    def test_bad_input_is_refused_before_any_request(self, kwargs, match):
+        client = FakeClient()
+        with pytest.raises(ValueError, match=match):
+            ValidationResource(client).run(**{**IDENTITY, **kwargs})
+        assert client.calls == []
+
+
+class TestMetricFlags:
+    def test_unset_flags_are_omitted_so_the_tier_default_applies(self):
+        client, _ = _run([{"job_id": "v1"}])
+        config = client.calls[0][2]["json"]["config"]
+        # Sending these as null would override the server-side tier default.
+        for flag in ("statistical", "stylised_facts", "impact",
+                     "volume_correlation", "fid", "mind"):
+            assert flag not in config, f"{flag} must be omitted when unset"
+        assert config == {"n_levels": 10}
+
+    @pytest.mark.parametrize(
+        "flag,value",
+        [("statistical", False), ("stylised_facts", True), ("impact", False),
+         ("volume_correlation", True), ("fid", False), ("mind", True),
+         ("lob", True), ("sample_period", "100ms"),
+         ("match_generated_sample", True),
+         ("plots", ["statistical.radar"])],
+    )
+    def test_explicit_options_are_forwarded(self, flag, value):
+        client, _ = _run([{"job_id": "v1"}], **{flag: value})
+        assert client.calls[0][2]["json"]["config"][flag] == value
+
+    def test_the_legacy_aliases_are_gone(self):
+        """run_* and l2_only/plot_data were two names for one thing."""
+        for dead in ("run_metrics", "run_impact", "run_stylised_facts",
+                     "run_inception_distances", "l2_only", "plot_data",
+                     "historical_output"):
+            with pytest.raises((TypeError, ValueError)):
+                ValidationResource(FakeClient()).run(
+                    sim_ids=SIM_IDS, **IDENTITY, **{dead: True}
+                )
+
+
+class TestSubmitOnly:
+    """run submits and returns. A real day takes minutes, which is far too
+    long to hold a request open, so status is get_job's job."""
+
+    def test_it_returns_the_submission_without_waiting(self):
+        client, result = _run([{"job_id": "v1", "status": "pending"}])
+        assert result == {"job_id": "v1", "status": "pending"}
+        assert [c[0] for c in client.calls] == ["POST"]
+
+    def test_a_missing_job_id_is_an_error(self):
+        with pytest.raises(ValueError, match="no job_id"):
+            _run([{"detail": "nope"}])
+
+    def test_it_does_not_poll(self):
+        assert not hasattr(ValidationResource, "_await")
+        import inspect
+
+        params = inspect.signature(ValidationResource.run).parameters
+        assert "poll_interval" not in params
+        assert "timeout" not in params
+
+
+class TestPlots:
+    """Figures arrive with the result, so get_job is what writes them."""
+
+    @staticmethod
+    def _fetch(responses, **kwargs):
+        client = FakeClient(responses)
+        return ValidationResource(client).get_job("v1", **kwargs)
+
+    def test_plots_requested_on_the_run_go_in_the_config(self):
+        client, _ = _run([{"job_id": "v1"}], plots=["statistical.radar"])
+        assert client.calls[0][2]["json"]["config"]["plots"] == ["statistical.radar"]
+
+    def test_nothing_is_written_when_the_job_has_no_plots(self, tmp_path):
+        job = self._fetch([_done()], plot_dir=str(tmp_path))
+        assert "plot_paths" not in job
+        assert list(tmp_path.iterdir()) == []
+
+    def test_plots_are_written_to_plot_dir(self, tmp_path):
+        target = tmp_path / "figs"
+        job = self._fetch(
+            [_done(plots={"distances": [{"name": "l1", "content_base64": PNG}]})],
+            plot_dir=str(target),
+        )
+        assert job["plot_paths"] == [str(target / "l1.png")]
+        assert (target / "l1.png").read_bytes().startswith(b"\x89PNG")
+
+    def test_plot_dir_is_created_if_absent(self, tmp_path):
+        target = tmp_path / "a" / "b"
+        self._fetch(
+            [_done(plots={"distances": [{"name": "l1", "content_base64": PNG}]})],
+            plot_dir=str(target),
+        )
+        assert (target / "l1.png").is_file()
+
+    def test_without_plot_dir_they_land_in_the_current_directory(self, tmp_path, monkeypatch):
+        monkeypatch.chdir(tmp_path)
+        job = self._fetch(
+            [_done(plots={"distances": [{"name": "radar", "content_base64": PNG}]})]
+        )
+        assert job["plot_paths"] == [str(tmp_path / "radar.png")]
+        assert (tmp_path / "radar.png").is_file()
+
+
+class TestOneEntryPoint:
+    def test_the_extra_run_methods_are_gone(self):
+        for dead in ("run_pipeline", "run_upload", "display_plots",
+                     "inception_distances"):
+            assert not hasattr(ValidationResource, dead)
+
+    def test_retrieval_still_works(self):
+        client = FakeClient([{"job_id": "v1"}, {"jobs": [], "total": 0}])
+        res = ValidationResource(client)
+        res.get_job("v1")
+        res.list_jobs(limit=5)
+        assert client.calls[0][:2] == ("GET", "/validation/jobs/v1")
+        assert client.calls[1][2]["params"] == {"limit": 5}
+
+
+class TestSimulatedFrameShapes:
+    """sim_files takes a path, a (name, bytes) pair, or a DataFrame."""
+
+    def _files_sent(self, entries):
+        client = FakeClient([{"job_id": "v1"}])
+        ValidationResource(client).run(sim_files=entries, **IDENTITY)
+        return client.calls[0][2]["files"]
+
+    def test_pair(self):
+        assert self._files_sent([("a.parquet", b"x")])[0][1] == ("a.parquet", b"x")
+
+    def test_path(self, tmp_path):
+        p = tmp_path / "sim.parquet"
+        p.write_bytes(b"data")
+        assert self._files_sent([str(p)])[0][1] == ("sim.parquet", b"data")
+
+    def test_each_frame_gets_its_own_name(self):
+        pd = pytest.importorskip("pandas")
+        frames = [pd.DataFrame({"a": [1]}), pd.DataFrame({"a": [2]})]
+        names = [f[1][0] for f in self._files_sent(frames)]
+        assert names == ["sim_0.parquet", "sim_1.parquet"]