simudyne-pulse 0.7.0.dev15__tar.gz → 0.7.0.dev17__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simudyne-pulse
-Version: 0.7.0.dev15
+Version: 0.7.0.dev17
 Summary: Python SDK for the Simudyne Pulse synthetic market data API
 Author-email: Simudyne <support@simudyne.com>
 License-Expression: MIT
@@ -85,6 +85,33 @@ population. `sim_files` groups the same way.
 A plain list is one unnamed population and keeps the flat shape exactly as
 before. The historical day is measured once however many groups there are.
 
+### Your own runs beside platform runs
+
+`sim_ids` and `sim_files` can be given together — your own model against
+platform simulations, on one set of figures, 25 runs in total across the two:
+
+```python
+job = client.validation.run(
+    symbol="TSCO", date="2026-06-23", provider="bmll", exchange="lse",
+    sim_files={"fm": ["my_run.parquet"]},
+    sim_ids={"abm": abm_ids},
+    plots=["statistical.radar", "stylised_facts.overall"],
+)
+```
+
+With both present each source is a population of its own, so a bare list gets
+a name rather than merging into whatever else is there:
+
+| passed | populations |
+| --- | --- |
+| files mapping + ids list | its names, plus `platform` |
+| files list + ids mapping | `uploaded`, plus its names |
+| both lists | `uploaded` and `platform` |
+| both mappings | their own names |
+| either one alone | exactly as before |
+
+The uploads are measured first and the platform runs follow.
+
 `plots` is the only plot switch: unset draws nothing, `True` draws every
 figure the enabled areas can draw, and a list draws just those ids. An area
 switched off draws nothing either way.

{simudyne_pulse-0.7.0.dev15 → simudyne_pulse-0.7.0.dev17}/README.md

@@ -59,6 +59,33 @@ population. `sim_files` groups the same way.
 A plain list is one unnamed population and keeps the flat shape exactly as
 before. The historical day is measured once however many groups there are.
 
+### Your own runs beside platform runs
+
+`sim_ids` and `sim_files` can be given together — your own model against
+platform simulations, on one set of figures, 25 runs in total across the two:
+
+```python
+job = client.validation.run(
+    symbol="TSCO", date="2026-06-23", provider="bmll", exchange="lse",
+    sim_files={"fm": ["my_run.parquet"]},
+    sim_ids={"abm": abm_ids},
+    plots=["statistical.radar", "stylised_facts.overall"],
+)
+```
+
+With both present each source is a population of its own, so a bare list gets
+a name rather than merging into whatever else is there:
+
+| passed | populations |
+| --- | --- |
+| files mapping + ids list | its names, plus `platform` |
+| files list + ids mapping | `uploaded`, plus its names |
+| both lists | `uploaded` and `platform` |
+| both mappings | their own names |
+| either one alone | exactly as before |
+
+The uploads are measured first and the platform runs follow.
+
 `plots` is the only plot switch: unset draws nothing, `True` draws every
 figure the enabled areas can draw, and a list draws just those ids. An area
 switched off draws nothing either way.

{simudyne_pulse-0.7.0.dev15 → simudyne_pulse-0.7.0.dev17}/pyproject.toml

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

{simudyne_pulse-0.7.0.dev15 → simudyne_pulse-0.7.0.dev17}/src/simudyne/client.py

@@ -45,7 +45,8 @@ class PulseABM:
     api_keys : ApiKeysResource
         Create, list and revoke API keys.
     data : DataResource
-        The catalog of calibrated symbols available to simulate.
+        The market data catalogue: what exists, what is calibrated,
+        and calibrating a day.
     simulation : SimulationResource
         Submit agent-based simulations and retrieve their results.
     validation : ValidationResource

simudyne_pulse-0.7.0.dev17/src/simudyne/resources/data.py

@@ -0,0 +1,348 @@
+"""Market data: what exists, what the agent-based model can simulate, and the
+one action that moves a symbol-day from the first to the second.
+
+Reached as ``client.data``. The three calls are one story:
+
+    available_data()    every symbol-day in the registry
+    calibrate()         calibrate one of them
+    calibrated_data()   the ones the ABM can now simulate
+
+A foundation-model run is prompted from anything in ``available_data``; an
+agent-based run needs the day to appear in ``calibrated_data`` first.
+"""
+
+AVAILABLE_DATA_PATH = "/data/available-data"
+CALIBRATED_DATA_PATH = "/data/calibrated-data"
+CALIBRATE_PATH = "/data/calibrate"
+
+
+class DataResource:
+    """Browse the market data catalogue and calibrate days in it.
+
+    Reached as ``client.data``. Every simulation is pinned to a symbol-day, so
+    this is the resource that tells you which ``provider`` / ``exchange`` /
+    ``symbol`` / ``cal_date`` combinations exist and which are ready to run.
+
+    Examples
+    --------
+    >>> catalog = client.data.calibrated_data(exchange="hkex_securities")
+    >>> for instrument in catalog["symbols"][:3]:
+    ...     print(instrument["symbol"], instrument["available_dates"][:2])
+    """
+
+    def __init__(self, client):
+        self._client = client
+
+    def available_data(
+        self,
+        model_id: str | None = None,
+        symbol: str | None = None,
+        q: str | None = None,
+        provider: str | None = None,
+        exchange: str | None = None,
+        date: str | None = None,
+        include_calibration_state: bool = False,
+        limit: int | None = None,
+        offset: int | None = None,
+    ):
+        """Every symbol-day in the data registry: what EXISTS.
+
+        The raw-data catalogue, so it answers both "what can a foundation model
+        be prompted with?" and "what could I calibrate?". Its counterpart is
+        :meth:`calibrated_data`, which lists only the days the agent-based
+        pipeline has already processed.
+
+        Every filter is applied in the database. The catalogue holds the whole
+        vendor universe (~15k symbols) and is never returned whole, so page
+        through it with ``limit`` and ``offset`` rather than asking for all of
+        it.
+
+        Parameters
+        ----------
+        model_id : str, optional
+            A model from :meth:`~simudyne.resources.fm.FmResource.models`.
+            Keeps only the markets that model's ``supported_data`` declares, so
+            what comes back is exactly what it will accept at
+            :meth:`~simudyne.resources.simulation.SimulationResource.run` with
+            ``engine="fm"``. An unknown id raises.
+        symbol : str, optional
+            Exact symbol, e.g. "700" or "TSCO".
+        q : str, optional
+            Case-insensitive substring match over the symbol.
+        provider : str, optional
+            Data provider, e.g. "omd" or "bmll". Narrows further within
+            ``model_id``'s markets when both are given.
+        exchange : str, optional
+            Exchange protocol, e.g. "lse" or "hkex_securities".
+        date : str, optional
+            Trading date "YYYY-MM-DD". Keeps only symbols with data on that
+            day, and returns only that day.
+        include_calibration_state : bool, default False
+            Also return ``calibrated_dates`` and ``calibrated_count`` per
+            symbol — which of its days the agent-based model has already
+            calibrated. Costs a second query, so it is off by default; it means
+            nothing to a foundation model.
+        limit : int, optional
+            Max symbols to return (1-200, default 50).
+        offset : int, optional
+            Symbols to skip, for paging alongside ``limit``.
+
+        Returns
+        -------
+        dict
+            ``{total, limit, offset, symbols}``, paged by symbol identity
+            rather than by row so a symbol's dates are never truncated.
+            ``total`` is the match count before paging. Each symbol has:
+
+            - symbol (str): the ticker, e.g. "700"
+            - provider (str), exchange (str): the market it came from
+            - dates (list of str): trading days present, "YYYY-MM-DD"
+            - calibrated_dates (list of str), calibrated_count (int): only
+              with ``include_calibration_state``
+
+            ``dates`` is always a list of strings, with or without calibration
+            state, so a caller never branches on the shape of the response.
+
+        Raises
+        ------
+        PulseAPIError
+            If the key is not pro or demo tier (403), ``model_id`` names a
+            model that is not registered (404), or ``date`` is not
+            ``YYYY-MM-DD`` (422).
+
+        See Also
+        --------
+        calibrated_data : The subset the agent-based model can simulate.
+        calibrate : Move one symbol-day from here to there.
+
+        Examples
+        --------
+        Search the registry:
+
+        >>> page = client.data.available_data(q="tsc", exchange="lse")
+        >>> page["total"]
+        3
+
+        What one model can be prompted with, which is the usual pre-run call:
+
+        >>> page = client.data.available_data(model_id="pulse-lob-1", limit=20)
+        >>> first = page["symbols"][0]
+        >>> first["symbol"], first["dates"][:2]
+        ('AZN', ['2026-06-22', '2026-06-23'])
+
+        Which of a symbol's days are already calibrated:
+
+        >>> page = client.data.available_data(
+        ...     symbol="700", include_calibration_state=True,
+        ... )
+        >>> entry = page["symbols"][0]
+        >>> len(entry["dates"]), entry["calibrated_count"]
+        (60, 4)
+        """
+        params = {
+            k: v for k, v in {
+                "model_id": model_id,
+                "symbol": symbol,
+                "q": q,
+                "provider": provider,
+                "exchange": exchange,
+                "date": date,
+                "include_calibration_state": include_calibration_state or None,
+                "limit": limit,
+                "offset": offset,
+            }.items() if v is not None
+        }
+        return self._client._request("GET", AVAILABLE_DATA_PATH, params=params or None)
+
+    def calibrated_data(
+        self,
+        symbol: str | None = None,
+        exchange: str | None = None,
+        provider: str | None = None,
+        date: str | None = None,
+        q: str | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+    ):
+        """Symbol-days the agent-based model can simulate: what is CALIBRATED.
+
+        Every entry is a valid ``symbol`` / ``provider`` / ``exchange`` /
+        ``cal_date`` for
+        :meth:`~simudyne.resources.simulation.SimulationResource.run` with
+        ``engine="abm"``. A day that exists but has never been calibrated
+        appears in :meth:`available_data` and not here; :meth:`calibrate` is
+        what moves it across.
+
+        Parameters
+        ----------
+        symbol : str, optional
+            Exact symbol, e.g. "700.HK".
+        exchange : str, optional
+            Exchange protocol, e.g. "hkex_securities".
+        provider : str, optional
+            Data provider, e.g. "omd" or "bmll".
+        date : str, optional
+            Calibration date "YYYY-MM-DD". Keeps only instruments calibrated
+            on that date, and narrows each one's ``available_dates`` to it.
+        q : str, optional
+            Case-insensitive substring match over ticker and company name.
+        limit : int, optional
+            Max instruments to return. Omitted, the whole calibrated catalogue
+            comes back — it is far smaller than the registry.
+        offset : int, optional
+            Instruments to skip, for paging alongside ``limit``.
+
+        Returns
+        -------
+        dict
+            ``{total, limit, offset, symbols}``, the same envelope as
+            :meth:`available_data`, paged by instrument. Each entry has:
+
+            - symbol (str): the ticker, e.g. "700.HK"
+            - company_name (str or None): the issuer's name where the vendor
+              reports one
+            - provider (str), exchange (str): the market it came from
+            - instrument_type, currency, tick_size, lot_size
+            - available_dates (list of dict): one per calibrated day, each with
+              ``date``, ``status``, ``stage``, ``number_of_msgs``,
+              ``volume_traded`` and ``reference_price``. Any ``date`` here is a
+              valid ``cal_date`` to run against
+            - avg_number_of_msgs, avg_volume_traded: averaged over the dates
+              returned, so a ``date`` filter narrows them too
+
+        Raises
+        ------
+        PulseAPIError
+            If a filter is malformed — most often ``date`` not in
+            ``YYYY-MM-DD`` form (422).
+
+        See Also
+        --------
+        available_data : Everything that exists, calibrated or not.
+
+        Examples
+        --------
+        The whole calibrated catalogue:
+
+        >>> everything = client.data.calibrated_data()
+        >>> everything["total"]
+        412
+
+        One instrument, to see which dates it can be run for:
+
+        >>> hits = client.data.calibrated_data(symbol="700.HK")
+        >>> [d["date"] for d in hits["symbols"][0]["available_dates"]]
+        ['2025-09-01', '2025-09-02', '2025-09-03']
+
+        Everything calibrated on one date, the usual way to pick a date that is
+        valid across several instruments:
+
+        >>> on_date = client.data.calibrated_data(date="2025-09-01")
+
+        Free-text search over ticker and company name, paged:
+
+        >>> page = client.data.calibrated_data(q="tencent", limit=10)
+        """
+        params = {
+            k: v for k, v in {
+                "symbol": symbol,
+                "exchange": exchange,
+                "provider": provider,
+                "date": date,
+                "q": q,
+                "limit": limit,
+                "offset": offset,
+            }.items() if v is not None
+        }
+        return self._client._request("GET", CALIBRATED_DATA_PATH, params=params or None)
+
+    def calibrate(
+        self,
+        symbol: str,
+        cal_date: str,
+        provider: str,
+        exchange: str,
+        simulations: int = None,
+        batch_size: int = None,
+        optimize_adj_params: bool = True,
+    ):
+        """Fit the agent-based model to one symbol-day.
+
+        Calibration is a data operation: its input is a day from
+        :meth:`available_data` and its output is an entry in
+        :meth:`calibrated_data`. It runs asynchronously — the call returns once
+        the job is queued, and the day appears in :meth:`calibrated_data` when
+        the pipeline finishes.
+
+        A symbol is identified by four fields: ``provider``, ``exchange``,
+        ``symbol`` and ``cal_date``.
+
+        Parameters
+        ----------
+        symbol : str
+            Trading symbol, e.g. "9999.HK".
+        cal_date : str
+            Trading day in YYYY-MM-DD format.
+        provider : str
+            Data provider the symbol is sourced from: "omd" or "bmll".
+        exchange : str
+            Exchange protocol name, e.g. "hkex_securities".
+        simulations : int, optional
+            Number of simulations to run during calibration.
+        batch_size : int, optional
+            Batch size for calibration runs.
+        optimize_adj_params : bool, default True
+            Whether to optimise adjustment parameters.
+
+        Returns
+        -------
+        dict
+            Calibration job submission result, containing the job identifier
+            and its accepted status.
+
+        Raises
+        ------
+        PulseAPIError
+            If the key is not demo tier (403), or there is no raw market data
+            for the symbol on ``cal_date`` (400).
+
+        Notes
+        -----
+        Calibration is only needed for a symbol-day that is not already
+        calibrated, and it is far slower than running against an existing
+        calibration. Check :meth:`calibrated_data` first — most instruments are
+        calibrated already.
+
+        Examples
+        --------
+        >>> job = client.data.calibrate(
+        ...     symbol="9999.HK",
+        ...     cal_date="2025-09-01",
+        ...     provider="omd",
+        ...     exchange="hkex_securities",
+        ... )
+
+        With an explicit budget, and adjustment-parameter optimisation off:
+
+        >>> job = client.data.calibrate(
+        ...     symbol="9999.HK",
+        ...     cal_date="2025-09-01",
+        ...     provider="omd",
+        ...     exchange="hkex_securities",
+        ...     simulations=500,
+        ...     batch_size=50,
+        ...     optimize_adj_params=False,
+        ... )
+        """
+        payload: dict = {
+            "symbol": symbol,
+            "cal_date": cal_date,
+            "provider": provider,
+            "exchange": exchange,
+            "optimize_adj_params": optimize_adj_params,
+        }
+        if simulations is not None:
+            payload["simulations"] = simulations
+        if batch_size is not None:
+            payload["batch_size"] = batch_size
+        return self._client._request("POST", CALIBRATE_PATH, json=payload)

simudyne_pulse-0.7.0.dev17/src/simudyne/resources/fm.py

@@ -0,0 +1,149 @@
+"""The foundation-model registry: what can run here, and what each accepts.
+
+RUNNING a foundation model is not here. ``client.simulation.run(engine="fm")``
+submits every simulation, agent-based or foundation-model, and
+``client.simulation`` polls and reads them both — an FM sim carries the same
+canonical ``sim_id``, differing only in its ``gen_method`` field
+(``FM-{model_id}_v{version}`` rather than ``ABM_v{version}``).
+
+What remains here is the registry, which is a catalogue of engines rather than
+a simulation, and the live streaming session, which has no job and no sim_id
+and so shares no lifecycle with the rest.
+
+Workflow:
+    1. ``models()`` — what can run here, and what each model accepts
+    2. ``client.data.available_data(model_id=...)`` — what it can be prompted
+       with
+    3. ``client.simulation.run(engine="fm", model_id=...)`` — submit; returns a
+       job_id and its sim_ids up front
+    4. ``client.simulation.get_job_status(job_id)`` until it is complete
+    5. ``client.simulation.get_sim_data(sim_id)`` — read the generated book
+"""
+
+MODELS_PATH = "/fm/models"
+LIVE_PATH = "/fm/live"
+
+
+class FmResource:
+    """The foundation models registered in this environment.
+
+    Reached as ``client.fm``. Use it to discover what can run and what each
+    model accepts, then submit through ``client.simulation.run(engine="fm")``
+    like any other simulation.
+
+    Every call on this resource requires a pro-tier key.
+
+    Examples
+    --------
+    The full workflow, from picking a model to reading the generated book —
+    note that only the first step is on this resource:
+
+    >>> import time
+    >>> model = client.fm.models()["models"][0]
+    >>> job = client.simulation.run(
+    ...     engine="fm",
+    ...     model_id=model["model_id"],
+    ...     symbol="700",
+    ...     cal_date="2025-09-02",
+    ...     provider="bmll",
+    ...     exchange="hkex_securities",
+    ...     duration_minutes=30,
+    ... )
+    >>> while not client.simulation.get_job_status(job["job_id"])["is_complete"]:
+    ...     time.sleep(30)
+    >>> book = client.simulation.get_sim_data(job["sim_ids"][0])
+    """
+
+    def __init__(self, client):
+        self._client = client
+
+    def models(self):
+        """Foundation models active in this environment.
+
+        Requires a pro-tier key.
+
+        Returns
+        -------
+        dict
+            Contains ``models``, a list of model dicts, each with:
+
+            - model_id (str): the id to pass to :meth:`run`
+            - version (str): the model build version
+            - production_name (str): branding name, empty for dev builds
+            - supported_data (list of dict): ``{provider, exchange}`` markets
+              the model accepts a prompt from; empty means any
+            - min_prompt_rows (int or None): context rows it needs to start
+            - model_args (dict): the knobs it accepts, each
+              ``{type, default, min, max, description}``
+            - resources (dict): ``{cpu, memory, gpu}`` it is scheduled with
+
+        Raises
+        ------
+        PulseAPIError
+            If the key is not pro tier — status 403.
+
+        Examples
+        --------
+        >>> for m in client.fm.models()["models"]:
+        ...     print(m["model_id"], m["version"], sorted(m["model_args"]))
+
+        Inspect one model's knobs before overriding them:
+
+        >>> models = client.fm.models()["models"]
+        >>> first = models[0]
+        >>> knobs = first["model_args"]
+        >>> knobs["temperature"]
+        {'type': 'float', 'default': 1.0, 'min': 0.1, 'max': 2.0, ...}
+        """
+        return self._client._request("GET", MODELS_PATH)
+
+    def live(
+        self,
+        model_id: str,
+        horizon: int = None,
+        seed: int = 42,
+        model_args: dict = None,
+    ):
+        """Start a live streaming session instead of a batch job.
+
+        Returns the token a live chart client uses to connect. Requires a
+        pro-tier key.
+
+        Parameters
+        ----------
+        model_id : str
+            A model from models().
+        horizon : int, optional
+            Frames to generate.
+        seed : int, default 42
+            Master random seed.
+        model_args : dict, optional
+            Overrides for the model's declared knobs.
+
+        Returns
+        -------
+        dict
+            Contains ``token`` — the connection token a live chart client
+            presents — plus ``job_id`` and ``model_id``.
+
+        Raises
+        ------
+        PulseAPIError
+            If ``model_id`` is unknown (404), ``model_args`` holds an unknown
+            or out-of-range key (400), or the key is not pro tier (403).
+
+        Examples
+        --------
+        >>> session = client.fm.live(model_id="tradefm-hkex", horizon=5000)
+        >>> print(session["token"])
+
+        A live session is not a batch job: nothing is queued, no ``sim_id`` is
+        minted, and there is no status to poll. The token is the whole
+        interface.
+        """
+        payload = {"model_id": model_id, "seed": seed}
+        if horizon is not None:
+            payload["horizon"] = horizon
+        if model_args:
+            payload["model_args"] = model_args
+        return self._client._request("POST", LIVE_PATH, json=payload)