simudyne-pulse 0.7.0.dev12__tar.gz → 0.7.0.dev14__tar.gz

{simudyne_pulse-0.7.0.dev12 → simudyne_pulse-0.7.0.dev14}/PKG-INFO

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

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

{simudyne_pulse-0.7.0.dev12 → simudyne_pulse-0.7.0.dev14}/src/simudyne/resources/validation.py

@@ -9,7 +9,7 @@ Submit, then poll::
 
     job = client.validation.run(
         symbol="BARC", date="2026-06-17", provider="bmll", exchange="lse",
-        sim_ids=[...], ticksize=0.05,
+        sim_ids=[...],
     )
     result = client.validation.get_job(job["job_id"])
     result["distances"]["spread"]["l1"]        # per simulation
@@ -27,6 +27,14 @@ 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.
 
+Tick size
+---------
+Read off the historical day — the metadata sidecar, else pulse_format's own
+metadata for that day's ``full_data.parquet``. It is not a parameter. The
+result reports ``metadata["ticksize"]`` and ``metadata["ticksize_source"]``;
+a source of ``"fallback"`` means none was found and 1.0 was assumed, which
+puts the impact response in price units rather than ticks.
+
 The historical gate
 -------------------
 Whether the historical half of the comparison comes back — the series in the
@@ -39,6 +47,7 @@ them.
 """
 
 import json
+from collections.abc import Iterable
 from pathlib import Path
 
 
@@ -146,7 +155,32 @@ def _save_plots(result: dict, plot_dir=None) -> list:
 
 
 class ValidationResource:
-    """Validate simulated market data against a historical day."""
+    """Score simulated market data against a real historical day.
+
+    Reached as ``client.validation``. A job compares one or more simulated runs
+    — either platform ``sim_ids`` or your own uploaded frames — against the
+    real day for the same instrument, and reports distances, distribution
+    overlaps, stylised-fact verdicts and FID/MIND scores.
+
+    Jobs are asynchronous: :meth:`run` returns a ``job_id`` and :meth:`get_job`
+    is polled until it is terminal. A validation of a real day takes minutes.
+
+    Examples
+    --------
+    >>> import time
+    >>> job = client.validation.run(
+    ...     symbol="BARC", date="2025-09-02",
+    ...     provider="bmll", exchange="lse",
+    ...     sim_ids=["sim_abc", "sim_def"],
+    ...     plots=True,
+    ... )
+    >>> while True:
+    ...     result = client.validation.get_job(job["job_id"], plot_dir="figures/")
+    ...     if result["status"] in ("completed", "failed"):
+    ...         break
+    ...     time.sleep(30)
+    >>> result["distances"]
+    """
 
     def __init__(self, client):
         self._client = client
@@ -160,7 +194,6 @@ class ValidationResource:
         *,
         sim_ids=None,
         sim_files=None,
-        ticksize: float = 1.0,
         statistical=None,
         stylised_facts=None,
         impact=None,
@@ -191,7 +224,10 @@ class ValidationResource:
             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"``.
+            Exchange, e.g. ``"lse"`` or ``"hkex_securities"``. The tick size
+            is read off the historical day for this instrument rather than
+            passed in; ``metadata["ticksize"]`` reports the value used and
+            ``metadata["ticksize_source"]`` where it came from.
         sim_ids : list of str or dict, optional
             Platform simulation IDs, 1 to 25. A flat list is one unnamed
             population. A mapping — ``{"fm": [...], "abm": [...]}`` — compares
@@ -203,8 +239,6 @@ class ValidationResource:
             Your own simulated runs, up to 25: paths, ``(filename, bytes)``
             pairs, or polars / pandas DataFrames in pulse format. Grouped the
             same way as ``sim_ids``. 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
@@ -249,7 +283,58 @@ class ValidationResource:
         Raises
         ------
         ValueError
-            If the parameters are invalid.
+            If neither or both of ``sim_ids`` and ``sim_files`` are given,
+            either is empty, more than 25 runs are passed, or ``n_levels``
+            is below 1. Also raised if the API
+            accepts the request but returns no ``job_id``.
+        PulseAPIError
+            If the instrument has no historical data for ``date``, a
+            ``sim_id`` is unknown, or the tier does not allow a requested
+            area.
+
+        Examples
+        --------
+        Platform simulations against the real day:
+
+        >>> job = client.validation.run(
+        ...     symbol="BARC",
+        ...     date="2025-09-02",
+        ...     provider="bmll",
+        ...     exchange="lse",
+        ...     sim_ids=["sim_abc", "sim_def"],
+        ... )
+        >>> job["job_id"]
+        'val_01H...'
+
+        Two named populations, compared against each other and the real day:
+
+        >>> job = client.validation.run(
+        ...     symbol="BARC", date="2025-09-02",
+        ...     provider="bmll", exchange="lse",
+        ...     sim_ids={"fm": ["sim_abc"], "abm": ["sim_def", "sim_ghi"]},
+        ... )
+
+        Your own frames, with only the areas you want and selected figures:
+
+        >>> job = client.validation.run(
+        ...     symbol="BARC", date="2025-09-02",
+        ...     provider="bmll", exchange="lse",
+        ...     sim_files=[my_dataframe],
+        ...     statistical=True,
+        ...     stylised_facts=True,
+        ...     impact=False,
+        ...     plots=["statistical.radar", "stylised_facts.overall"],
+        ... )
+
+        L2 snapshots resampled onto a one-second grid:
+
+        >>> job = client.validation.run(
+        ...     symbol="BARC", date="2025-09-02",
+        ...     provider="bmll", exchange="lse",
+        ...     sim_files=["book_snapshots.parquet"],
+        ...     lob=True,
+        ...     sample_period="1s",
+        ... )
         """
         if (sim_ids is None) == (sim_files is None):
             raise ValueError("Pass exactly one of sim_ids or sim_files")
@@ -258,15 +343,29 @@ class ValidationResource:
         if sim_files is not None and not sim_files:
             raise ValueError("sim_files must not be empty")
         given = sim_ids if sim_ids is not None else sim_files
+        name = "sim_ids" if sim_ids is not None else "sim_files"
+        if isinstance(given, dict):
+            # A bare string is iterable, so {"fm": "one.parquet"} used to count
+            # its characters as runs and fail with "Maximum 25 simulations" —
+            # a number the caller never wrote. Say what is actually wrong.
+            for group, runs in given.items():
+                if isinstance(runs, (str, bytes)):
+                    raise ValueError(
+                        f"{name}[{group!r}] must be a list of runs, not a "
+                        f"single {type(runs).__name__} — write [{runs!r}]"
+                    )
+                if not isinstance(runs, Iterable):
+                    raise ValueError(
+                        f"{name}[{group!r}] must be a list of runs, not "
+                        f"{type(runs).__name__}"
+                    )
         count = (
-            sum(len(v) for v in given.values())
+            sum(len(list(v)) for v in given.values())
             if isinstance(given, dict)
             else len(given)
         )
         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")
 
@@ -298,7 +397,6 @@ class ValidationResource:
                         if isinstance(sim_ids, dict)
                         else list(sim_ids)
                     ),
-                    "ticksize": ticksize,
                     "config": config,
                 },
             )
@@ -332,7 +430,6 @@ class ValidationResource:
                     "date": date,
                     "provider": provider,
                     "exchange": exchange,
-                    "ticksize": str(ticksize),
                     "config": json.dumps(config),
                 },
             )
@@ -367,6 +464,34 @@ class ValidationResource:
             ``stylised_fact_verdicts``, ``volume_correlation``,
             ``fid_scores``, ``mind_scores`` — enough to rebuild every figure —
             plus ``plot_paths`` when figures were written.
+
+        Raises
+        ------
+        PulseAPIError
+            If ``job_id`` is unknown or belongs to another account — status
+            404.
+
+        Examples
+        --------
+        >>> result = client.validation.get_job(job_id)
+        >>> result["status"]
+        'running'
+
+        Poll to completion, writing any figures into a directory:
+
+        >>> import time
+        >>> while True:
+        ...     result = client.validation.get_job(job_id, plot_dir="figures/")
+        ...     if result["status"] in ("completed", "failed"):
+        ...         break
+        ...     time.sleep(30)
+        >>> print(result["plot_paths"])
+        ['figures/statistical.radar.png', 'figures/stylised_facts.overall.png']
+
+        With named populations, the scores come back keyed by name:
+
+        >>> result["fid_scores"]
+        {'fm': 0.142, 'abm': 0.318}
         """
         job = self._client._request("GET", f"{JOBS_PATH}/{job_id}")
         if (job or {}).get("plots"):
@@ -384,6 +509,24 @@ class ValidationResource:
         Returns
         -------
         dict
-            ``{"jobs": list, "total": int}``.
+            Contains ``jobs``, a list of job summaries newest first, and
+            ``total``, the count before ``limit`` was applied.
+
+        Raises
+        ------
+        PulseAPIError
+            If the key is invalid, revoked or expired — status 401.
+
+        Examples
+        --------
+        >>> listing = client.validation.list_jobs(limit=10)
+        >>> for job in listing["jobs"]:
+        ...     print(job["job_id"], job["status"], job["symbol"], job["date"])
+
+        Find the most recent completed job and read it back:
+
+        >>> done = [j for j in listing["jobs"] if j["status"] == "completed"]
+        >>> newest = done[0]
+        >>> result = client.validation.get_job(newest["job_id"])
         """
         return self._client._request("GET", JOBS_PATH, params={"limit": limit})

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simudyne-pulse
-Version: 0.7.0.dev12
+Version: 0.7.0.dev14
 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.dev12 → simudyne_pulse-0.7.0.dev14}/tests/test_validation.py

@@ -83,7 +83,6 @@ class TestWhatToValidate:
             ({"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"),
         ],
     )
@@ -289,3 +288,68 @@ class TestPlotEverything:
     def test_plot_all_is_gone(self):
         with pytest.raises(TypeError):
             _run([{"job_id": "v1"}], plot_all=True)
+
+
+class TestGroupShape:
+    """A group's value is a list of runs. A bare string is not one.
+
+    ``{"fm": "one.parquet"}`` is the natural thing to write for a group of
+    one, and it used to count the path's characters as runs and fail with
+    "Maximum 25 simulations per validation job" — a number the caller never
+    wrote anywhere.
+    """
+
+    @staticmethod
+    def _submit(**kwargs):
+        return ValidationResource(FakeClient([{"job_id": "v1"}])).run(
+            **{**IDENTITY, **kwargs}
+        )
+
+    def test_a_string_names_itself_not_the_file_count(self):
+        with pytest.raises(ValueError, match=r"sim_files\['fm'\] must be a list"):
+            self._submit(sim_files={"fm": "one.parquet"})
+
+    def test_the_message_shows_the_fix(self):
+        with pytest.raises(ValueError, match=r"write \['one.parquet'\]"):
+            self._submit(sim_files={"fm": "one.parquet"})
+
+    def test_sim_ids_groups_are_checked_the_same_way(self):
+        with pytest.raises(ValueError, match=r"sim_ids\['abm'\] must be a list"):
+            self._submit(sim_ids={"abm": "sim_abc"})
+
+    def test_a_non_iterable_group_is_named_plainly(self):
+        with pytest.raises(ValueError, match=r"not NoneType"):
+            self._submit(sim_ids={"abm": None})
+
+    def test_a_real_list_still_passes(self):
+        client = FakeClient([{"job_id": "v1"}])
+        ValidationResource(client).run(sim_ids={"abm": ["a", "b"]}, **IDENTITY)
+        assert client.calls[0][2]["json"]["sim_ids"] == {"abm": ["a", "b"]}
+
+    def test_the_count_still_catches_too_many(self):
+        with pytest.raises(ValueError, match="Maximum 25"):
+            self._submit(sim_ids={"a": ["x"] * 13, "b": ["y"] * 13})
+
+
+class TestTickSizeIsNotAsked:
+    """It is read off the historical day, so passing one is a mistake.
+
+    The value a caller passed never reached a computation — the impact
+    response has always used the one pulse-check looks up — so accepting it
+    only let a result disagree with itself.
+    """
+
+    def test_run_does_not_take_it(self):
+        with pytest.raises(TypeError, match="ticksize"):
+            ValidationResource(FakeClient([{"job_id": "v1"}])).run(
+                sim_ids=SIM_IDS, ticksize=0.1, **IDENTITY
+            )
+
+    def test_it_is_not_sent(self):
+        client, _ = _run([{"job_id": "v1"}])
+        assert "ticksize" not in client.calls[0][2]["json"]
+
+    def test_an_upload_does_not_send_it_either(self):
+        client = FakeClient([{"job_id": "v1"}])
+        ValidationResource(client).run(sim_files=[("a.parquet", b"x")], **IDENTITY)
+        assert "ticksize" not in client.calls[0][2]["data"]