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

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

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

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

{simudyne_pulse-0.7.0.dev14 → simudyne_pulse-0.7.0.dev16}/src/simudyne/client.py

@@ -12,6 +12,75 @@ from simudyne.exceptions import PulseAPIError
 
 
 class PulseABM:
+    """Client for the Simudyne Pulse synthetic market data API.
+
+    The client holds the API key and HTTP session, and exposes every endpoint
+    through a resource attribute (``client.simulation``, ``client.data``, ...).
+    Construct it once and reuse it; the underlying :class:`requests.Session`
+    keeps connections alive across calls.
+
+    Transient failures (HTTP 429, 502, 503, 504) and network timeouts are
+    retried automatically with exponential backoff. Any other non-2xx response
+    raises :class:`~simudyne.exceptions.PulseAPIError`.
+
+    Parameters
+    ----------
+    api_key : str, optional
+        Pulse API key (``pk_live_...``). Falls back to the ``SIMUDYNE_API_KEY``
+        environment variable when omitted.
+    base_url : str, optional
+        API root, with no trailing slash. Falls back to the
+        ``SIMUDYNE_BASE_URL`` environment variable, then to
+        ``https://pulse-api.simudyne.com``.
+    timeout : int, optional
+        Per-request timeout in seconds. Defaults to 30.
+    max_retries : int, default 3
+        Retry attempts for transient errors. Backoff is ``2 ** attempt``
+        seconds, so the default waits 1s, 2s then 4s before giving up.
+
+    Attributes
+    ----------
+    profile : ProfileResource
+        Account details, usage and download history.
+    api_keys : ApiKeysResource
+        Create, list and revoke API keys.
+    data : DataResource
+        The catalog of calibrated symbols available to simulate.
+    simulation : SimulationResource
+        Submit agent-based simulations and retrieve their results.
+    validation : ValidationResource
+        Score synthetic data against real data.
+    fm : FmResource
+        Foundation-model generation and its job lifecycle.
+    fix : FixResource
+        FIX gateway usage.
+    simulator_gym : SimulatorGymResource
+        Gym-style reinforcement-learning environment over a WebSocket.
+
+    Raises
+    ------
+    ValueError
+        If no API key is given and ``SIMUDYNE_API_KEY`` is unset.
+
+    Examples
+    --------
+    Key taken from the environment:
+
+    >>> import os
+    >>> os.environ["SIMUDYNE_API_KEY"] = "pk_live_..."
+    >>> client = PulseABM()
+
+    Key passed explicitly, against a non-default deployment:
+
+    >>> client = PulseABM(
+    ...     api_key="pk_live_...",
+    ...     base_url="https://pulse-api-dev.simudyne.com",
+    ...     timeout=60,
+    ... )
+    >>> client.profile.get()["email"]
+    'you@example.com'
+    """
+
     DEFAULT_BASE_URL = "https://pulse-api.simudyne.com"
     DEFAULT_TIMEOUT = 30
     RETRYABLE_STATUS_CODES = {429, 502, 503, 504}
@@ -41,6 +110,8 @@ class PulseABM:
         from simudyne.resources.simulation import SimulationResource
         from simudyne.resources.simulator_gym import SimulatorGymResource
         from simudyne.resources.validation import ValidationResource
+        from simudyne.resources.fm import FmResource
+        from simudyne.resources.fix import FixResource
 
         self.profile = ProfileResource(self)
         self.api_keys = ApiKeysResource(self)
@@ -50,6 +121,8 @@ class PulseABM:
         self.simulation = SimulationResource(self)
         self.simulator_gym = SimulatorGymResource(self)
         self.validation = ValidationResource(self)
+        self.fm = FmResource(self)
+        self.fix = FixResource(self)
 
     def _request_with_retries(self, method: str, url: str, **kwargs):
         """Execute request with timeout and exponential backoff for transient errors."""
@@ -89,6 +162,12 @@ class PulseABM:
         response = self._request_with_retries(method, url, **kwargs)
         return response.json()
     
+    def _request_text(self, method: str, endpoint: str, **kwargs):
+        """Like _request, for endpoints that answer text/plain not JSON."""
+        url = f"{self.base_url}{endpoint}"
+        response = self._request_with_retries(method, url, **kwargs)
+        return response.text
+
     def _request_csv(self, method, endpoint, **kwargs):
         PAGE_SIZE = 100000
         params = kwargs.get("params", {})

simudyne_pulse-0.7.0.dev16/src/simudyne/exceptions.py

@@ -0,0 +1,44 @@
+class PulseAPIError(Exception):
+    """Raised when the Pulse API returns a non-2xx response.
+
+    Every resource method raises this on API-level failure. Transient statuses
+    (429, 502, 503, 504) are retried by the client first, so receiving this
+    means the request failed after all retries were exhausted, or failed with a
+    status that is not worth retrying.
+
+    Parameters
+    ----------
+    status_code : int
+        HTTP status code returned by the API.
+    detail : str
+        Message from the response body's ``detail`` field, or the raw response
+        text when the body is not JSON.
+
+    Attributes
+    ----------
+    status_code : int
+        HTTP status code returned by the API.
+    detail : str
+        Human-readable explanation of the failure.
+
+    Examples
+    --------
+    >>> try:
+    ...     client.simulation.get_job_status("does-not-exist")
+    ... except PulseAPIError as exc:
+    ...     print(exc.status_code, exc.detail)
+    404 Job not found
+
+    Retry only on rate limiting, and let anything else surface:
+
+    >>> try:
+    ...     client.simulation.run(...)
+    ... except PulseAPIError as exc:
+    ...     if exc.status_code != 429:
+    ...         raise
+    """
+
+    def __init__(self, status_code: int, detail: str):
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"API Error ({status_code}): {detail}")

{simudyne_pulse-0.7.0.dev14 → simudyne_pulse-0.7.0.dev16}/src/simudyne/resources/api_keys.py

@@ -1,4 +1,18 @@
 class ApiKeysResource:
+    """Create, list and revoke the API keys on your account.
+
+    Reached as ``client.api_keys``. Keys are the only credential the SDK
+    accepts, and key material is returned exactly once, by :meth:`create`.
+
+    Examples
+    --------
+    Mint a key for a job, use it, then revoke it:
+
+    >>> key = client.api_keys.create(name="Nightly backtest")
+    >>> run_client = PulseABM(api_key=key["api_key"])
+    >>> client.api_keys.revoke(key_id=key["api_key_id"])
+    """
+
     def __init__(self, client):
         self._client = client
 
@@ -25,6 +39,11 @@ class ApiKeysResource:
             warning : str
                 A reminder that the key will not be shown again.
 
+        Raises
+        ------
+        PulseAPIError
+            If the account has reached its key limit, or ``name`` is rejected.
+
         Examples
         --------
         >>> new_key = client.api_keys.create(name="Training script")
@@ -52,6 +71,11 @@ class ApiKeysResource:
             - last_used_at (str or None): None until the key is first used
             - expires_at (str or None): None for keys that do not expire
 
+        Raises
+        ------
+        PulseAPIError
+            If the calling key is invalid or has been revoked.
+
         Examples
         --------
         >>> for key in client.api_keys.list():
@@ -75,9 +99,20 @@ class ApiKeysResource:
         dict
             The revocation result.
 
+        Raises
+        ------
+        PulseAPIError
+            If ``key_id`` does not exist or does not belong to your account.
+
         Examples
         --------
         >>> new_key = client.api_keys.create(name="Training script")
         >>> client.api_keys.revoke(key_id=new_key["api_key_id"])
+
+        Revoking the key you are currently authenticating with locks you out
+        of the API, so mint the replacement first:
+
+        >>> replacement = client.api_keys.create(name="Rotated")
+        >>> client.api_keys.revoke(key_id=old_key_id)
         """
         return self._client._request("DELETE", f"/api-keys/{key_id}")

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

@@ -0,0 +1,109 @@
+AVAILABLE_SYMBOLS_PATH = "/data/available-symbols"
+
+
+class DataResource:
+    """Browse the catalog of calibrated instruments you can simulate.
+
+    Reached as ``client.data``. Every simulation is pinned to a symbol that has
+    already been calibrated, so this is the resource that tells you which
+    ``provider`` / ``exchange`` / ``symbol`` / ``cal_date`` combinations exist.
+
+    Examples
+    --------
+    >>> catalog = client.data.get_available_symbols(exchange="hkex_securities")
+    >>> for instrument in catalog[:3]:
+    ...     dates = instrument["available_dates"]
+    ...     print(instrument["symbol"], dates[:2])
+    """
+
+    def __init__(self, client):
+        self._client = client
+
+    def get_available_symbols(
+        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,
+    ):
+        """List calibrated instruments and the dates available for each.
+
+        All arguments are optional filters; with none passed the whole catalog
+        comes back, as before.
+
+        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 instrument's
+            available_dates to it.
+        q : str, optional
+            Case-insensitive substring match over ticker and company name.
+        limit : int, optional
+            Max instruments to return.
+        offset : int, optional
+            Instruments to skip (for paging alongside limit).
+
+        Returns
+        -------
+        list of dict
+            One entry per instrument, each with:
+
+            - symbol (str): ticker, e.g. "700.HK"
+            - exchange (str): exchange protocol, e.g. "hkex_securities"
+            - provider (str): data provider, e.g. "omd"
+            - available_dates (list of str): calibration dates, "YYYY-MM-DD",
+              any of which is a valid ``cal_date`` for
+              :meth:`~simudyne.resources.simulation.SimulationResource.run`
+
+        Raises
+        ------
+        PulseAPIError
+            If a filter is malformed — most often ``date`` not in
+            ``YYYY-MM-DD`` form.
+
+        Examples
+        --------
+        The whole catalog:
+
+        >>> everything = client.data.get_available_symbols()
+        >>> len(everything)
+        412
+
+        One instrument, to see which dates it can be run for:
+
+        >>> hits = client.data.get_available_symbols(symbol="700.HK")
+        >>> first = hits[0]
+        >>> print(first["available_dates"])
+        ['2025-09-01', '2025-09-02', '2025-09-03']
+
+        Free-text search over ticker and company name, paged:
+
+        >>> page = client.data.get_available_symbols(q="tencent", limit=10)
+
+        Everything calibrated on one date, which is the usual way to pick a
+        date that is valid across several instruments:
+
+        >>> on_date = client.data.get_available_symbols(date="2025-09-01")
+        """
+        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", AVAILABLE_SYMBOLS_PATH, params=params or None)

simudyne_pulse-0.7.0.dev16/src/simudyne/resources/fix.py

@@ -0,0 +1,75 @@
+"""FIX venue usage: what you have run over a FIX session.
+
+The FIX venue itself is a raw-TCP FIX 4.4 acceptor, not an HTTP API — you reach
+it with your own FIX engine, not with this SDK. What lives here is the one
+HTTP endpoint a FIX client wants: a record of what it has run.
+
+Runs are written by the venue rather than by the client, because the venue is
+what knows the session, the account and the start parameters. Only the shape of
+a run is kept -- symbol, date, scenario, speed, horizon. No orders, no
+schedules, no fills: that is your strategy, and it is not ours to store.
+"""
+
+USAGE_PATH = "/fix/usage"
+
+
+class FixResource:
+    """Usage records for simulations started over the FIX venue.
+
+    Reached as ``client.fix``. The venue itself is raw-TCP FIX 4.4 and is not
+    driven from this SDK — you connect to it with your own FIX engine. This
+    resource only reads back what the venue recorded.
+
+    Examples
+    --------
+    >>> usage = client.fix.usage()
+    >>> print(usage["total_runs"], "runs,", usage["simulated_seconds"], "s")
+    """
+
+    def __init__(self, client):
+        self._client = client
+
+    def usage(self, user_id: str = None):
+        """Simulations you have started over FIX, and how many times.
+
+        Parameters
+        ----------
+        user_id : str, optional
+            Another account to read, which requires an admin key.
+            Omit it for your own usage.
+
+        Returns
+        -------
+        dict
+            Usage summary containing:
+
+            - total_runs (int): FIX sessions recorded
+            - simulated_seconds (float): total horizon across those runs
+            - by_symbol / by_scenario / by_cal_date (dict): run counts
+            - runs (list of dict): one ``{symbol, cal_date, scenario, runs}``
+              per distinct combination, most-run first
+            - last_run_at (str or None): when the most recent one started,
+              None if nothing has been run
+            - truncated (bool): True if the history hit the server's cap
+
+        Raises
+        ------
+        PulseAPIError
+            If ``user_id`` is given without an admin key, or names an account
+            that does not exist.
+
+        Examples
+        --------
+        >>> usage = client.fix.usage()
+        >>> print(f"{usage['total_runs']} FIX runs")
+        >>> runs = usage["runs"]
+        >>> for run in runs[:5]:
+        ...     print(f"  {run['symbol']} {run['cal_date']} "
+        ...           f"{run['scenario']}: {run['runs']}x")
+
+        Read another account, which needs an admin key:
+
+        >>> client.fix.usage(user_id="usr_01H...")
+        """
+        params = {"user_id": user_id} if user_id else None
+        return self._client._request("GET", USAGE_PATH, params=params)