simudyne-pulse 0.9.0.dev2__tar.gz → 0.9.0.dev3__tar.gz

{simudyne_pulse-0.9.0.dev2/src/simudyne_pulse.egg-info → simudyne_pulse-0.9.0.dev3}/PKG-INFO

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

{simudyne_pulse-0.9.0.dev2 → simudyne_pulse-0.9.0.dev3}/pyproject.toml

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

{simudyne_pulse-0.9.0.dev2 → simudyne_pulse-0.9.0.dev3}/src/simudyne/client.py

@@ -11,6 +11,30 @@ import math
 from simudyne.exceptions import PulseAPIError, error_from_response  # noqa: F401
 
 
+def _never_reached_server(error: Exception) -> bool:
+    """Whether a transport error happened before the request was sent.
+
+    A connect timeout, a refused connection or a failed DNS lookup means the
+    API never saw the request, so even a submit is safe to send again. A
+    read timeout or a dropped connection may come after the API acted.
+    """
+    if isinstance(error, requests.exceptions.ConnectTimeout):
+        return True
+    if isinstance(error, requests.exceptions.ConnectionError):
+        from urllib3.exceptions import NewConnectionError
+
+        seen = set()
+        cause = error
+        while cause is not None and id(cause) not in seen:
+            seen.add(id(cause))
+            if isinstance(cause, NewConnectionError):
+                return True
+            reason = getattr(cause, "reason", None)
+            nested = cause.args[0] if getattr(cause, "args", None) else None
+            cause = reason or (nested if isinstance(nested, BaseException) else None) or cause.__cause__
+    return False
+
+
 class PulseABM:
     """Client for the Simudyne Pulse synthetic market data API.
 
@@ -19,9 +43,20 @@ class PulseABM:
     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`.
+    Transient failures are retried automatically with exponential backoff,
+    but only where sending the request twice is safe. A read (GET, and the
+    bulk download) is retried on HTTP 502, 503, 504, timeouts and connection
+    errors. A call that creates or changes something — submitting a
+    simulation or validation, minting or revoking a key — is retried only on
+    503 or when the connection never opened, because a 502, 504 or read
+    timeout may arrive after the API acted. A 429 is retried only when it
+    carries ``Retry-After``; the download quota's 429 is raised at once. Any
+    other non-2xx response, and a retried status still failing once the
+    retries run out, raises :class:`~simudyne.exceptions.PulseAPIError`. A timeout or
+    connection failure that outlasts the retries is not wrapped: it surfaces
+    as the underlying :class:`requests.Timeout` or
+    :class:`requests.ConnectionError`, so catch those alongside
+    ``PulseAPIError`` if you need to handle every failure.
 
     Parameters
     ----------
@@ -36,7 +71,8 @@ class PulseABM:
         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.
+        seconds, so the default waits 1s, 2s then 4s before giving up; a
+        ``Retry-After`` header, when sent, is honoured (capped at 60 s).
 
     Attributes
     ----------
@@ -83,6 +119,9 @@ class PulseABM:
     DEFAULT_BASE_URL = "https://pulse-api.simudyne.com"
     DEFAULT_TIMEOUT = 30
     RETRYABLE_STATUS_CODES = {429, 502, 503, 504}
+    #: Methods safe to send twice. DELETE is left out on purpose: a revoke
+    #: that succeeded but whose answer was lost would come back as a 404.
+    IDEMPOTENT_METHODS = {"GET", "HEAD", "OPTIONS"}
 
     def __init__(
         self,
@@ -117,9 +156,25 @@ class PulseABM:
         self.simulation = SimulationResource(self)
         self.validation = ValidationResource(self)
 
-    def _request_with_retries(self, method: str, url: str, **kwargs):
-        """Execute request with timeout and exponential backoff for transient errors."""
+    def _request_with_retries(self, method: str, url: str, idempotent=None, **kwargs):
+        """Execute a request, retrying only what is safe to send twice.
+
+        A read (GET, or a POST the caller marks ``idempotent=True``, such as
+        the bulk download) is retried on 502/503/504, on a timeout and on a
+        connection failure. A call that creates or changes something —
+        submitting a simulation or validation, minting or revoking a key,
+        launching a live session — is retried only when the API cannot have
+        acted on it: the connection never opened, or the API answered 503.
+        A 502, 504 or read timeout on such a call may arrive after the job
+        was queued, and retrying it used to queue a second one.
+
+        A 429 is retried only when it carries ``Retry-After``, as a rate
+        limiter's does. The API's own 429 is the free-tier download quota,
+        which does not clear in seconds; it is raised at once.
+        """
         kwargs.setdefault("timeout", self.timeout)
+        if idempotent is None:
+            idempotent = method.upper() in self.IDEMPOTENT_METHODS
         last_exception = None
 
         for attempt in range(self.max_retries + 1):
@@ -129,23 +184,45 @@ class PulseABM:
                 if response.ok:
                     return response
 
-                if response.status_code in self.RETRYABLE_STATUS_CODES and attempt < self.max_retries:
-                    delay = 2 ** attempt
-                    time.sleep(delay)
+                if attempt < self.max_retries and self._should_retry(
+                    response, idempotent
+                ):
+                    time.sleep(self._retry_delay(response, attempt))
                     continue
 
                 raise error_from_response(response)
 
             except (requests.exceptions.Timeout, requests.exceptions.ConnectionError) as e:
                 last_exception = e
-                if attempt < self.max_retries:
-                    delay = 2 ** attempt
-                    time.sleep(delay)
+                if attempt < self.max_retries and (
+                    idempotent or _never_reached_server(e)
+                ):
+                    time.sleep(2 ** attempt)
                     continue
                 raise
 
         raise last_exception
 
+    def _should_retry(self, response, idempotent: bool) -> bool:
+        status = response.status_code
+        if status == 429:
+            return "Retry-After" in response.headers
+        if status not in self.RETRYABLE_STATUS_CODES:
+            return False
+        return idempotent or status == 503
+
+    @staticmethod
+    def _retry_delay(response, attempt: int) -> float:
+        """``Retry-After`` seconds when the server gives them (capped at 60),
+        otherwise exponential backoff: 1, 2, 4 s."""
+        header = response.headers.get("Retry-After")
+        if header is not None:
+            try:
+                return min(max(float(header), 0.0), 60.0)
+            except ValueError:
+                pass
+        return 2 ** attempt
+
     def _request(self, method: str, endpoint: str, **kwargs):
         url = f"{self.base_url}{endpoint}"
         response = self._request_with_retries(method, url, **kwargs)

{simudyne_pulse-0.9.0.dev2 → simudyne_pulse-0.9.0.dev3}/src/simudyne/resources/api_keys.py

@@ -8,6 +8,7 @@ class ApiKeysResource:
     --------
     Mint a key for a job, use it, then revoke it:
 
+    >>> from simudyne import PulseABM
     >>> 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"])
@@ -46,7 +47,8 @@ class ApiKeysResource:
         Raises
         ------
         PulseAPIError
-            If the account has reached its key limit, or ``name`` is rejected.
+            If the calling key is invalid, revoked or expired — status 401.
+            There is no per-account key limit.
 
         See Also
         --------
@@ -65,7 +67,8 @@ class ApiKeysResource:
 
         The full key is never returned after creation; only ``key_prefix``,
         the first 12 characters, is stored. That is enough to tell keys apart
-        and not enough to reconstruct one.
+        and not enough to reconstruct one. Revoked keys are not listed, and
+        at most 100 keys are returned.
 
         Returns
         -------
@@ -75,7 +78,7 @@ class ApiKeysResource:
             - api_key_id (str): the handle to pass to :meth:`revoke`
             - key_prefix (str): first 12 characters, e.g. "pk_live_ab12"
             - name (str): the label you gave it
-            - is_active (bool): False once revoked
+            - is_active (bool): always True, since revoked keys are omitted
             - created_at (str): when it was created
             - 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
@@ -111,12 +114,14 @@ class ApiKeysResource:
         Returns
         -------
         dict
-            The revocation result.
+            ``{"message": "API key revoked"}``.
 
         Raises
         ------
         PulseAPIError
-            If ``key_id`` does not exist or does not belong to your account.
+            Status 404 if ``key_id`` does not exist, does not belong to your
+            account, or has already been revoked; 401 if the calling key is
+            invalid.
 
         See Also
         --------
@@ -131,7 +136,10 @@ class ApiKeysResource:
         Revoking the key you are currently authenticating with locks you out
         of the API, so mint the replacement first:
 
+        >>> from simudyne import PulseABM
+        >>> old_key_id = client.api_keys.list()[0]["api_key_id"]
         >>> replacement = client.api_keys.create(name="Rotated")
+        >>> client = PulseABM(api_key=replacement["api_key"])
         >>> client.api_keys.revoke(key_id=old_key_id)
         """
         return self._client._request("DELETE", f"/api-keys/{key_id}")

{simudyne_pulse-0.9.0.dev2 → simudyne_pulse-0.9.0.dev3}/src/simudyne/resources/data.py

@@ -108,9 +108,11 @@ class DataResource:
         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).
+            If the key is not pro or demo tier (403); ``model_id`` names a
+            model that is not registered (404) or matches more than one
+            (400); ``date`` is not ``YYYY-MM-DD``, ``limit`` is outside
+            1-200 or ``offset`` is negative (422); or, with ``model_id``, the
+            model registry (pulse-orchestrator) could not be reached (502).
 
         See Also
         --------
@@ -189,8 +191,8 @@ class DataResource:
         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.
+            Max instruments to return, 1-1000. Omitted, the whole calibrated
+            catalogue comes back — it is far smaller than the registry.
         offset : int, optional
             Instruments to skip, for paging alongside ``limit``.
 
@@ -215,8 +217,9 @@ class DataResource:
         Raises
         ------
         PulseAPIError
-            If a filter is malformed — most often ``date`` not in
-            ``YYYY-MM-DD`` form (422).
+            If ``limit`` is outside 1-1000 or ``offset`` is negative (422).
+            Available on every tier. A malformed ``date`` is not rejected:
+            it simply matches nothing, and ``total`` comes back 0.
 
         See Also
         --------
@@ -274,7 +277,7 @@ class DataResource:
         :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.
+        the pipeline finishes. Demo tier only.
 
         A symbol is identified by four fields: ``provider``, ``exchange``,
         ``symbol`` and ``cal_date``.
@@ -299,14 +302,25 @@ class DataResource:
         Returns
         -------
         dict
-            Calibration job submission result, containing the job identifier
-            and its accepted status.
+            status : str
+                "calibration_queued".
+            symbol : str
+                The symbol as submitted.
+            cal_date : str
+                The date as submitted.
+
+            There is no job id: progress is not pollable through the API.
+            Watch :meth:`calibrated_data` for the day to appear.
 
         Raises
         ------
         PulseAPIError
-            If the key is not demo tier (403), or there is no raw market data
-            for the symbol on ``cal_date`` (400).
+            If the key is not demo tier (403), ``provider`` or ``exchange``
+            is not a recognised value (422), or the calibration service is
+            unreachable (503). Missing raw market data for the symbol-day is
+            not detected here: the job is queued and fails later in the
+            pipeline, so the day simply never appears in
+            :meth:`calibrated_data`.
 
         See Also
         --------
@@ -324,17 +338,19 @@ class DataResource:
         Examples
         --------
         >>> job = client.data.calibrate(
-        ...     symbol="9999.HK",
-        ...     cal_date="2025-09-01",
+        ...     symbol="700.HK",
+        ...     cal_date="2025-09-02",
         ...     provider="omd",
         ...     exchange="hkex_securities",
         ... )
+        >>> job["status"]
+        'calibration_queued'
 
         With an explicit budget, and adjustment-parameter optimisation off:
 
         >>> job = client.data.calibrate(
-        ...     symbol="9999.HK",
-        ...     cal_date="2025-09-01",
+        ...     symbol="700.HK",
+        ...     cal_date="2025-09-02",
         ...     provider="omd",
         ...     exchange="hkex_securities",
         ...     simulations=500,

{simudyne_pulse-0.9.0.dev2 → simudyne_pulse-0.9.0.dev3}/src/simudyne/resources/fix.py

@@ -1,7 +1,8 @@
 """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
+The FIX venue itself is a raw-TCP FIX 5.0 SP2 acceptor (FIXT.1.1 session
+layer; FIX 4.4 is not accepted), 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
@@ -16,8 +17,8 @@ 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
+    Reached as ``client.fix``. The venue itself is raw-TCP FIX 5.0 SP2 over
+    FIXT.1.1 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
@@ -35,14 +36,18 @@ class FixResource:
         Parameters
         ----------
         user_id : str, optional
-            Another account to read, which requires an admin key.
-            Omit it for your own usage.
+            Another account to read, which requires an admin key. Omit it
+            for your own usage — or, with an admin key, for estate-wide
+            totals across every account. An unknown ``user_id`` is not an
+            error: it returns an empty summary.
 
         Returns
         -------
         dict
             Usage summary containing:
 
+            - user_id (str or None): the account summarised; None for an
+              admin's estate-wide totals
             - total_runs (int): FIX sessions recorded
             - simulated_seconds (float): total horizon across those runs
             - by_symbol / by_scenario / by_cal_date (dict): run counts
@@ -51,12 +56,13 @@ class FixResource:
             - 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
+              of 5,000 runs, in which case only the newest 5,000 are counted
 
         Raises
         ------
         PulseAPIError
-            If ``user_id`` is given without an admin key, or names an account
-            that does not exist.
+            If ``user_id`` names another account and the key is not an admin
+            key (403), or the key is invalid, revoked or expired (401).
 
         See Also
         --------
@@ -74,6 +80,12 @@ class FixResource:
         Read another account, which needs an admin key:
 
         >>> client.fix.usage(user_id="usr_01H...")
+
+        With an admin key and no ``user_id``, the whole estate:
+
+        >>> estate = client.fix.usage()
+        >>> estate["user_id"] is None
+        True
         """
         params = {"user_id": user_id} if user_id else None
         return self._client._request("GET", USAGE_PATH, params=params)

{simudyne_pulse-0.9.0.dev2 → simudyne_pulse-0.9.0.dev3}/src/simudyne/resources/fm.py

@@ -32,7 +32,11 @@ class FmResource:
     model accepts, then submit through ``client.simulation.run(engine="fm")``
     like any other simulation.
 
-    Every call on this resource requires a pro-tier key.
+    :meth:`models` and :meth:`live` require a pro- or demo-tier key.
+    :meth:`registry`, :meth:`register`, :meth:`activate` and
+    :meth:`deactivate` require a key whose account has the admin flag
+    (``is_admin`` in :meth:`~simudyne.resources.profile.ProfileResource.get`);
+    tier plays no part in those four.
 
     Examples
     --------
@@ -61,7 +65,7 @@ class FmResource:
     def models(self):
         """Foundation models active in this environment.
 
-        Requires a pro-tier key.
+        Requires a pro- or demo-tier key.
 
         Returns
         -------
@@ -84,7 +88,8 @@ class FmResource:
         Raises
         ------
         PulseAPIError
-            If the key is not pro tier — status 403.
+            If the key is not pro or demo tier (403), or the model registry
+            (pulse-orchestrator) cannot be reached (502).
 
         See Also
         --------
@@ -124,11 +129,12 @@ class FmResource:
         Raises
         ------
         PulseAPIError
-            If the key is not an admin key — status 403.
+            If the key's account lacks the admin flag (403), or the
+            orchestrator cannot be reached (502).
 
         See Also
         --------
-        models : The active models only, for any pro key.
+        models : The active models only, for any pro or demo key.
         register : Add a model or a new version of one.
 
         Examples
@@ -148,6 +154,7 @@ class FmResource:
         supported_data: list | None = None,
         min_prompt_rows: int | None = None,
         production_name: str = "",
+        testdata: dict | None = None,
         active: bool = True,
     ):
         """Admin: register a model image, or a new version of one.
@@ -178,6 +185,11 @@ class FmResource:
             Context rows it needs to start inference.
         production_name : str, default ""
             The name to promote it under, ``{model}-{market}-{version}-{size}``.
+        testdata : dict, optional
+            The real day baked into the image as its test data,
+            ``{"provider", "exchange", "symbol", "date"}``. Test-data runs are
+            minted under that day, so their sim_ids name it instead of
+            ``na:na:testdata:na``.
         active : bool, default True
             Whether :meth:`models` lists it.
 
@@ -190,8 +202,12 @@ class FmResource:
         Raises
         ------
         PulseAPIError
-            If the key is not an admin key (403), or a field is rejected (400
-            or 422).
+            If the key's account lacks the admin flag (403); ``image`` is not
+            found in its container registry, or ``model_args`` or
+            ``supported_data`` is malformed (400); a field has the wrong type
+            (422); the deployment's registry is a read-only manifest, so
+            models cannot be registered through the API (501); or the
+            orchestrator, or the image check, cannot be reached (502).
 
         See Also
         --------
@@ -217,6 +233,7 @@ class FmResource:
         for name, value in (
             ("resources", resources), ("model_args", model_args),
             ("supported_data", supported_data), ("min_prompt_rows", min_prompt_rows),
+            ("testdata", testdata),
         ):
             if value is not None:
                 payload[name] = value
@@ -239,7 +256,9 @@ class FmResource:
         Raises
         ------
         PulseAPIError
-            If the key is not an admin key (403) or the model is unknown (404).
+            If the key's account lacks the admin flag (403), the model is
+            unknown (404), the deployment's registry is a read-only manifest
+            (501), or the orchestrator cannot be reached (502).
 
         See Also
         --------
@@ -270,7 +289,9 @@ class FmResource:
         Raises
         ------
         PulseAPIError
-            If the key is not an admin key (403) or the model is unknown (404).
+            If the key's account lacks the admin flag (403), the model is
+            unknown (404), the deployment's registry is a read-only manifest
+            (501), or the orchestrator cannot be reached (502).
 
         See Also
         --------
@@ -293,7 +314,7 @@ class FmResource:
         """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.
+        pro- or demo-tier key.
 
         Parameters
         ----------
@@ -316,7 +337,9 @@ class FmResource:
         ------
         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).
+            or out-of-range key (400), the key is not pro or demo tier (403),
+            this deployment cannot host live sessions (501), or the
+            orchestrator cannot be reached (502).
 
         See Also
         --------

{simudyne_pulse-0.9.0.dev2 → simudyne_pulse-0.9.0.dev3}/src/simudyne/resources/profile.py

@@ -70,7 +70,13 @@ class ProfileResource:
         """Return your request count for the current calendar month.
 
         Resets on the 1st, and counts *requests* rather than simulations —
-        one ``run()`` of 100 Monte Carlo runs is a single request here.
+        one ``run()`` of 100 Monte Carlo runs is a single request here. Only
+        the routes that log usage are counted: the data routes, the
+        simulation routes (run, LRM run, jobs and their status, results and
+        logs, per-sim files, params, metrics and data, bulk download, cached
+        and sample), validation ``run`` and ``run/upload``, FM ``live`` and
+        the historical routes. Profile, API-key, validation job reads, FM
+        model management and FIX usage calls are not counted.
 
         Returns
         -------
@@ -82,10 +88,10 @@ class ProfileResource:
             total_requests : int
                 Requests so far this month.
             by_endpoint : dict
-                Request count keyed by endpoint path. The keys are the
-                concrete paths that were called, so a job-scoped endpoint
-                appears once per job id rather than as a template — aggregate
-                by prefix if you want per-endpoint totals.
+                Request count keyed by route label. Job- and sim-scoped
+                routes are logged under their template, e.g.
+                ``"/simulation/jobs/{job_id}/status"``, not once per concrete
+                job id, so each key is already a per-endpoint total.
 
         Raises
         ------
@@ -102,12 +108,13 @@ class ProfileResource:
         >>> usage = client.profile.usage()
         >>> print(f"{usage['month']}: {usage['total_requests']} requests")
 
-        Aggregate the per-path counts back into per-endpoint totals:
+        Roll the per-route counts up into per-area totals:
 
         >>> from collections import Counter
         >>> totals = Counter()
-        >>> for path, count in usage["by_endpoint"].items():
-        ...     totals[path.split("/")[1]] += count
+        >>> for route, count in usage["by_endpoint"].items():
+        ...     totals[route.split("/")[1]] += count
+        >>> print(totals.most_common())
         """
         return self._client._request("GET", "/profile/usage")
 
@@ -134,7 +141,14 @@ class ProfileResource:
             downloaded_groups : list of str or None
                 Every group you have ever downloaded. None when unlimited.
             downloaded_group_details : list of dict or None
-                The same groups, each with a ``downloaded_at`` timestamp.
+                The same groups, newest first, each a dict with
+                ``job_key`` (str, the group, as in ``downloaded_groups``)
+                and ``downloaded_at`` (ISO timestamp str, or None).
+
+        Raises
+        ------
+        PulseAPIError
+            If the key is invalid, revoked or expired — status 401.
 
         See Also
         --------
@@ -147,11 +161,6 @@ class ProfileResource:
         A request that would exceed the allowance returns HTTP 429 without
         charging anything, so a partial download never silently eats quota.
 
-        Raises
-        ------
-        PulseAPIError
-            If the key is invalid, revoked or expired — status 401.
-
         Examples
         --------
         >>> quota = client.profile.downloads()